TCP/IP for z/VM
SSL Server - Configuration Basics and Overview

The information and instructions that follow are provided to help one configure the z/VM SSL server pool, as provided after installation of a z/VM deliverable.

The information that follows is intended for use in conjunction with the following publications:


SSL Server Default Environment and Layout

After a z/VM system has been installed, a predefined SSL Server pool is defined and in place for use with the default TCP/IP stack server (TCPIP). This server pool is identified with the prefix SSL and is comprised of five pool servers:

  SSL00001
  SSL00002
  SSL00003
  SSL00004
  SSL00005

In addition, an applicable SSL Discontiguous Saved Segment (DCSS) Management Agent virtual machine (SSLDCSSM) is defined and ready for use.

The IBM DTCPARMS file supplied as part of the z/VM deliverable includes applicable :nick.name :type.class and :nick.name :type.server entries for both the SSL server pool and the SSL DCSS agent servers.

Last, all applicable SFS directory definitions, enrollment and authorizations for the SSL pool servers have been implemented as part of the z/VM deliverable.


Basic Configuration Steps

  1. Set Up a Key Database

    Use the instructional information provided in TCP/IP Planning and Customization, Chapter16: Configuring the SSL Server under the heading Step 6: Set Up the Certificate (Key) Database to define and prepare an SSL certificate database (a z/VM key database) for use by the SSL server pool.

  2. Store applicable DigiCert CA Certificates, required for secure FTP connecitions with ECuRep and other IBM servers, into the Key Database
  3. If the SSL server pool has not already been configured for use and is operational, continue with the steps that follow.

  4. Logon the TCPMAINT user ID.
  5. Run the SSLPOOL utility with the PLAN operand to generate configuration information that is applicable to the installation default environment:
      sslpool plan vmsys tcpmaint ssl tcpip 5
    

    The SSLPOOL PLANINFO file that results is comprised of sample CP directory definitions, sample DTCPARMS file entries and sample TCP/IP server configuration statements.

    Note:
    The majority of the information provided in the produced SSLPOOL PLANINFO file pertains to definitions that already exist as part of the installed system.

    The PLANINFO content produced at this point is intended to serve as reference information, so specific configuration changes that are needed can be correctly implemented.

  6. Review the content of the SSLPOOL PLANINFO file, and make note of the following sections:
    • The DTCPARMS entry for the SSL server pool, which is identified with this comment/header:
      * -----------------------------------------------------------------------------
      * Example DTCPARMS Pool SSL 'Server' Entry
      * -----------------------------------------------------------------------------
      
    • The TCP/IP stack server configuration file entry, which is identified with this comment/header:
      * -----------------------------------------------------------------------------
      * Example TCP/IP Server Configuration (PROFILE TCPIP) Modifications
      * -----------------------------------------------------------------------------
      
    These two entries identify the statements that will, or might, require your action for modification.
  7. Update the TCP/IP server configuration file (PROFILE TCPIP, or its equivalent):
    1. If necessary, access the TCP/IP server configuration minidisk (TCPMAINT 198, by default).

      access 198 d

    2. Edit the PROFILE TCPIP file:

      xedit profile tcpip d

    3. Add the SSLSERVERID and SSLLIMITS statements, as cited in applicable PLANINFO file section, just mentioned.

      The relevant statements are:

        sslserverid  *  timeout 30
        ssllimits maxsessions 3000 maxpersslserver 600
      
    4. Save the updated stack configuration file.

      file

  8. Assess whether the nodeID or SYSTEM DTCPARMS file, used for your installation, needs to be modified at this time.

    If the key database defined for SSL server use has been named Database.kdb (as cited in the steps associated with the Set Up a Key Database preparation step, noted above) — then no DTCPARMS file changes are necessary at this time.

    If a key database name different from Database.kdb has been used, a DTCPARMS file update is necessary so this database file is correctly identified for use.

    1. Edit the nodeID or SYSTEM DTCPARMS file, as appropriate for your installation.

      xedit system dtcparms d

    2. Add the following stanza to this file:
        :nick.SSL*        :type.server   :class.ssl
          :stack.TCPIP
          :vmlink. .DIR VMSYS:TCPMAINT.SSLPOOL_SSL <. A FORCERW>
          :parms. KEYFile /etc/gskadm/keydb_filename
      
      where keydb_filename is the file name (with mixed case respected) of the key database file created for use with the SSL server pool.

      Note:
      Do NOT copy the IBM DTCPARMS file (in part, or in its entirety) to create a nodeID or SYSTEM DTCPARMS file that contains your customizations. Doing so can make more extensive TCP/IP server customizations more difficult over time, and also can create situations where server initialization errors are introduced.

    3. Save the updated DTCPARMS configuration file.

      file

  9. Initialize the TCP/IP Stack and SSL Server Pool for TLS services to be available.

    1. If the TCP/IP stack server is already in operation, it must be re-initialized (re-IPLed) so the updates to the PROFILE TCPIP file can become effective. Use the NETSTAT commaand below to shutdown the TCP/IP stack server, and after its completion, the CP XAUTOLOG command to restart the stack:
      
        netstat cp ext
        xautolog tcpip
      
      Next, the SSL server pool can be manually initialized using this command:

      ssladmin start ( sslserver all

      Afterward, confirm the SSL server pool is operational, via the NETSTAT CONIG SSL command (for which a successful response is shown here):

       netstat config ssl
       VM TCP/IP Netstat Level 640       TCP/IP Server Name: TCPIP
       SSL Server User ID: SSL00001   Status: Active   Connections: 0
       SSL Server User ID: SSL00003   Status: Active   Connections: 0
       SSL Server User ID: SSL00005   Status: Active   Connections: 0
       SSL Server User ID: SSL00002   Status: Active   Connections: 0
       SSL Server User ID: SSL00004   Status: Active   Connections: 0
       Maximum Session System Limit:  3000
       Maximum Session Server Limit:  600
       SSL Session High-Water Mark:   0
       Ready;
      
    2. If the TCP/IP stack server instead is to be recycled, use these commands to accomplish this:

      netstat cp ext
      xautolog tcpip
      

      The TCPIP server itself should then initialize the SSL server pool. Use the NETSTAT CONIG SSL command, mentioned above, to confirm the SSL server pool is operational.

  10. Logoff the TCPMAINT user ID. The changes necessary for initialization and use of the SSL server pool and TCP/IP (stack) servers now should be complete.