IBM Support

PH16222: DEVELOPMENT FIXES

A fix is available

Subscribe

You can track all active APARs for this component.

 

APAR status

  • Closed as new function.

Error description

  • Enhancements to zERT Network Analyzer
    

Local fix

Problem summary

  • ****************************************************************
    * USERS AFFECTED:                                              *
    * All users of V2R3 IBM z/OS Management                        *
    * Facility for HSMA23A: IBM zERT Network                       *
    * Analyzer                                                     *
    ****************************************************************
    * PROBLEM DESCRIPTION:                                         *
    * This APAR significantly changes the way                      *
    * the zERT Network Analyzer uses Db2 for                       *
    * z/OS. Prior to this APAR, the zERT                           *
    * Network Analyzer dynamically created                         *
    * short-lived tables and tablespaces in                        *
    * the database to hold query results that                      *
    * are displayed through the zERT Network                       *
    * Analyzer's Report tab. These tables are                      *
    * called 'Query Result Tables.'  The use                       *
    * of these dynamically-generated tables                        *
    * required the zERT Network Analyzer's                         *
    * database user ID to have privileges                          *
    * that are typically not granted to Db2                        *
    * application user IDs.                                        *
    ****************************************************************
    * RECOMMENDATION:                                              *
    * Apply PTF.                                                   *
    ****************************************************************
    

Problem conclusion

  • With this APAR, no Db2 for z/OS database objects are created
    dynamically and the privileges required by the zERT Network
    Analyzer's database user ID are reduced to only those required
    to INSERT, SELECT, UPDATE and DELETE data in tables that are
    explicitly created by the database administrator (DBA). Among
    those tables are a new set of partitioned Query Result Tables,
    with the number of partitions being configurable by the DBA.
    
    For more information on the documentation updates associated
    with this support, see the following link:
    https://www.ibm.com/support/pages/node/1117347
    
    Before starting the zERT Network Analyzer plug-in a database
    administrator must generate and apply the updated Data
    Definition Language (DDL) commands to the zERT Network Analyzer
    database on Db2 for z/OS. These DDL commands will define the
    required database schema version (1.3.x) for release HSMA23A.
    
    To support the new partitioned Query Result Tables, significant
    changes are required to the zERT Network Analyzer's database
    schema. These changes are reflected in the sample database
    schema tooling provided with this APAR:
    - IZUZNADT DDL template
    - (New) IZUZNADA DDL template used for customization of
      schema and table names
    - IZUZNADI variable substitution sample
    - IZUZNADG DDL generation REXX exec
    
    The database schema tooling can be used to generate DDL for
    either:
    - updating an existing zERT Network Analyzer database's
      schema, or
    - creating a brand new zERT Network Analyzer database.
    
    Choosing a DDL template
    -----------------------
    If an instance of the zERT Network Analyzer database exists
    prior to applying this APAR it was created using a prior version
    of the IZUZNADT template. Therefore, the IZUZNADT template
    provided with this APAR must be used.
    
    If a new zERT Network Analyzer database is being created, then
    choose which of the following templates to use.
    
    IZUZNADT:
      This template uses the fixed schema name 'SYSIBM_EZB_ZNADB'
      and fixed table names. If local naming conventions allow
      for these fixed names, then use this template to
      create the database schema for version 1.3.0 for release
      HSMA23A.
    
    IZUZNADA:
      This template allows custom schema and/or table names for the
      base objects and creates aliases for the tables using the
      schema name and table names that the zERT Network Analyzer
      depends on. If the default schema name and/or table names
      do not adhere to local naming conventions then use this
      template to create the database schema for version 1.3.1 for
      release HSMA23A.
    
    New template variables
    ----------------------
    Several new variables have been added to the IZUZNADT template
    and are also part of the IZUZNADA template. Two of these
    variables require special attention and planning:
    
      <QRTParts>
    
        Specifies the number of partitions to be created for each
        Query Result Table. THIS VALUE DETERMINES THE MAXIMUM
        NUMBER OF CONCURRENT OPEN ZERT NETWORK ANALYZER REPORTS
        ACROSS ALL LOGGED-IN USERS. Each active report will be
        assigned exclusive access to one partition in each of the
        Query Result Tables as long as that report is open in the
        web browser. Because of this, coordination with the DBA
        is required to determine an appropriate number of partitions
    
        to ensure that the database will have sufficient partitions
        to support the community of zERT Network Analyzer users.
    
        To determine the number of partitions needed, consider
        the number of users that will be using the zERT Network
        Analyzer as well as the number of reports each user might
        have open at any given time (a single user can have multiple
        reports open at one time, each in its own web browser tab).
        Multiply those two numbers together to determine the maximum
        possible number of open reports. The <QRTParts> value
        should be AT LEAST this value - increase this value by an
        appropriate 'extra room' percentage to ensure there is room
        for growth. To summarize:
    
        <QRTParts> = ((#OfUsers * #OfReportsPerUser) * extraSpace%)
    
        By default, the IZUZNADI sample sets <QRTParts> to 20.
    
      <database> and <QRTDatabase>
    
        <database>
    
          Specifies the name of the database that contains all the
          zERT Network Analyzer's persistent tables (all tables
          except the Query Result Tables). By default, the IZUZNADI
          sample sets this to 'ZNADB' which is the name that was
          explicitly specified in previous versions of the IZUZNADT
          template. If an existing database is being updated, then
          keep the default value of 'ZNADB'. If creating a
          brand new zERT Network Analyzer database, then choose any
          valid database name.
    
        <QRTDatabase>
    
          Specifies the name of the database that contains the
          Query Result Tables. Since partitioned Query Result
          Tables are new with this APAR, this database is also new.
          The Query Result Tables may be stored in the same
          database as the persistent tables or in a different
          database. To use the same database, set the <QRTDatabase>
          and <database> variables to the same value. To use
          different databases, specify a different values for
          <QRTDatabase>. By default, the IZUZNADI sample sets this
          to 'ZNAQRDB', placing the Query Result Tables in their
          own database.
    
    Other new variables added to the templates are:
    
    - Index names
        Another addition to the DDL templates is the ability to
        customize the names of the different indexes defined over
        the various zERT Network Analyzer tables. By default, the
        IZUZNADI sample specifies the index names that were
        explicitly specified in earlier versions of the IZUZNADT
        template. If updating an existing zERT Network
        Analyzer database that was built using that template, then
        use these default names. Otherwise, specifying any valid
        index names that meets local naming conventions is allowed.
    
    - <schema> - IZUZNADA TEMPLATE ONLY
        Specifies the custom schema name to use. All of the tables
        and indexes in the zERT Network Analyzer database will be
        created under this schema name and aliases will be created
        for all of the tables using the fixed schema name
        'SYSIBM_EZB_ZNADB' referenced by the JPA annotations in the
        zERT Network Analyzer plug-in. By default, the IZUZNADI
        sample sets this to 'CUSTOM_EZB_ZNADB'.
    
    - Table names - IZUZNADA TEMPLATE ONLY
        One variable is provided for each zERT Network Analyzer
        table to specify that table's name. Any of these variables
        may be set to any valid table name. The tables in the
        database will be created using these table names and the
        schema name specified by the <schema> variable. Aliases on
        these names will also be created for the tables using the
        fixed schema name 'SYSIBM_EZB_ZNADB' and the fixed table
        names referenced by the zERT Network Analyzer plug-in. By
        default, the IZUZNADI sample sets the table name variables
        to the names referenced by the zERT Network Analyzer
        plug-in.
    
    
    Generating customized DDL using the database schema tooling
    ===========================================================
    
    To update an existing zERT Network Analyzer database...
    -------------------------------------------------------
    1. Make a copy of the IZUZNADI sample and customize that copy
       with the appropriate values for your environment. If a
       customized variable substitution data set based on a prior
       IZUZNADI sample already exists, then carry those
       customizations over into the sample included with this APAR
       since a number of new variables have been added as described
       above.
    
    2. Identify the schema version and release of the existing zERT
       Network Analyzer database. To do this, log into the zERT
       Network Analyzer and go to the Settings->Database Settings
       panel. If the database schema version is NOT shown here,
       then your database schema version is 1.1.0. Otherwise, the
       displayed value indicate the schema version and release.
    
    3. Run the IZUZNADG exec specifying the following:
       - IZUZNADT template that is provided with this APAR
       - The customized variable substitution data set based on
         IZUZNADI provided with this APAR
       - The name of the output DDL data set
       - The DBVER(n.n.n) parameter where n.n.n is the database
         schema version of your database as determined in step 2.
    
       For example, assume the following:
       - the latest template and exec are under the current HLQ as
         IZUZNADT and IZUZNADG, respectively
       - the customized variable substitution data set is MYVARS
       - the generated DDL is to be written to NEWDDL
       - the current database schema version is 1.2.0
       - the current database schema release is HSMA23A which
         confirms the correct templates will be used to update the
         database
    
       Based on the information above, invoke IZUZNADG as follows:
    
        IZUZNADG MYVARS NEWDDL IZUZNADT DBVER(1.2.0)
    
       This will generate the customized DDL needed to update the
       zERT Network Analyzer database schema for this APAR.
    
       For more information on running the IZUZNADG exec, see the
       IZUZNADG online help by issuing IZUZNADG --HELP at the TSO
       command prompt.
    
    4. Use the generated DDL to update the zERT Network Analyzer
       database schema.
    
       Note that no data migration is required for this APAR - only
       the schema changes as generated using the IZUZNADx tooling.
    
    Once these steps are completed successfully, the zERT Network
    Analyzer is ready to use.
    
    To create a new zERT Network Analyzer database...
    -------------------------------------------------
    1. Select between the IZUZNADT and IZUZNADA DDL templates as
       described above.
    2. Make a copy of the IZUZNADI sample and customize that copy
       with the appropriate values for the local environment,
       including the new variables described above.
    3. Run the IZUZNADG exec specifying the following:
       - the selected template that is provided with this APAR
       - the customized variable substitution data set based on
         IZUZNADI provided with this APAR
       - the name of the output DDL data set.
    
       For example, assume the following:
       - the IZUZNADA template was selected
       - the latest template and exec are under the current HLQ as
         IZUZNADT and IZUZNADG, respectively
       - the customized variable substitution data set is MYVARS
       - the generated DDL is to be written to NEWDDL
    
       Based on the information above, invoke IZUZNADG as follows:
    
         IZUZNADG MYVARS NEWDDL IZUZNADA
    
       This will generate the customized DDL needed to create the
       zERT Network Analyzer database schema for this APAR.
    
       For more information on running the IZUZNADG exec, see the
       IZUZNADG online help by issuing IZUZNADG --HELP at the TSO
       command prompt.
    
    4. Use the generated DDL to create the zERT Network Analyzer
       database schema.
    
    Once these steps are completed successfully, proceed to log into
    the zERT Network Analyzer plug-in. The associated database
    connectivity information must be specified on the
    Settings->Database settings panel.
    
    
    Database privileges for database user ID
    ========================================
    
    The zERT Network Analyzer performs all of its database
    operations under a single z/OS user ID that is configured on the
    Network Analyzer's Database Settings panel. This is called the
    zERT Network Analyzer's 'database user ID'.
    
    Before starting the zERT Network Analyzer plug-in, provide the
    database user ID with the following privileges to ensure proper
    operation of the zERT Network Analyzer's various functions:
    
    The INSERT, SELECT, UPDATE, DELETE privilege for the following
    tables:
     1 - SYSIBM_EZB_ZNADB.APPL
     2 - SYSIBM_EZB_ZNADB.DATAMGMTHISTORY
     3 - SYSIBM_EZB_ZNADB.DATASET
     4 - SYSIBM_EZB_ZNADB.SECURITY_SESSION
     5 - SYSIBM_EZB_ZNADB.SESSION_STATISTICS
     6 - SYSIBM_EZB_ZNADB.IPSEC_INFO
     7 - SYSIBM_EZB_ZNADB.SSH_INFO
     8 - SYSIBM_EZB_ZNADB.TLS_INFO
     9 - SYSIBM_EZB_ZNADB.TOPOLOGY
    10 - SYSIBM_EZB_ZNADB.OPENJPA_SEQUENCE_TABLE
    11 - SYSIBM_EZB_ZNADB.QUERY
    12 - SYSIBM_EZB_ZNADB.SCOPE_FLTR
    13 - SYSIBM_EZB_ZNADB.SCOPE_FLTR_ENDPT
    14 - SYSIBM_EZB_ZNADB.SCOPE_FLTR_SYSSPEC
    15 - SYSIBM_EZB_ZNADB.SEC_FLTR
    16 - SYSIBM_EZB_ZNADB.SEC_IPSEC_FLTR
    17 - SYSIBM_EZB_ZNADB.SEC_SSH_FLTR
    18 - SYSIBM_EZB_ZNADB.SEC_TLS_FLTR
    19 - SYSIBM_EZB_ZNADB.FILTEREDSECURITYSESSIONIDS
    20 - SYSIBM_EZB_ZNADB.TCPSERVER_SUMMARIES
    21 - SYSIBM_EZB_ZNADB.TCPCLIENT_SUMMARIES
    22 - SYSIBM_EZB_ZNADB.EEPEER_SUMMARIES
    23 - SYSIBM_EZB_ZNADB.TCPSERVER_CLIENTDETAILS
    24 - SYSIBM_EZB_ZNADB.TCPCLIENT_CLIENTDETAILS
    25 - SYSIBM_EZB_ZNADB.EEPEER_CLIENTDETAILS
    26 - SYSIBM_EZB_ZNADB.TCPSERVER_CLEARSECURITYSESSIONDETAILS
    27 - SYSIBM_EZB_ZNADB.TCPSERVER_IPSECSECURITYSESSIONDETAILS
    28 - SYSIBM_EZB_ZNADB.TCPSERVER_SSHSECURITYSESSIONDETAILS
    29 - SYSIBM_EZB_ZNADB.TCPSERVER_TLSSECURITYSESSIONDETAILS
    30 - SYSIBM_EZB_ZNADB.TCPCLIENT_CLEARSECURITYSESSIONDETAILS
    31 - SYSIBM_EZB_ZNADB.TCPCLIENT_IPSECSECURITYSESSIONDETAILS
    32 - SYSIBM_EZB_ZNADB.TCPCLIENT_SSHSECURITYSESSIONDETAILS
    33 - SYSIBM_EZB_ZNADB.TCPCLIENT_TLSSECURITYSESSIONDETAILS
    34 - SYSIBM_EZB_ZNADB.EEPEER_CLEARSECURITYSESSIONDETAILS
    35 - SYSIBM_EZB_ZNADB.EEPEER_IPSECSECURITYSESSIONDETAILS
    
    The database user ID NO LONGER REQUIRES the following privileges
    as it did in previous service levels:
    
    36 - SELECT privilege on the table SYSIBM.SYSTABLES
    37 - CREATEIN privilege on schema EZB_EZB_ZNADB
    38 - CREATETAB privilege on database DSNDB04
    39 - CREATETS privilege on database DSNDB04
    40 - USE OF privilege to the bufferpool specified in the Db2
         subsystem parameter TBSBP8K
    
    As such, permissions 36 through 40 should be removed from the
    zERT Network Analyzer database user ID if they are currently
    granted.
    

Temporary fix

Comments

APAR Information

  • APAR number

    PH16222

  • Reported component name

    ZOSMF ZERT NW A

  • Reported component ID

    5655S28ZE

  • Reported release

    23A

  • Status

    CLOSED UR1

  • PE

    NoPE

  • HIPER

    NoHIPER

  • Special Attention

    NoSpecatt / Xsystem

  • Submitted date

    2019-08-29

  • Closed date

    2020-01-14

  • Last modified date

    2020-02-04

  • APAR is sysrouted FROM one or more of the following:

  • APAR is sysrouted TO one or more of the following:

    UI67390

Modules/Macros

  • IZUNASEC IZUZNADA IZUZNADG IZUZNADI IZUZNADT IZUZNAHP IZUZNAHS
    IZUZNAPS IZUZNAPX
    

Fix information

  • Fixed component name

    ZOSMF ZERT NW A

  • Fixed component ID

    5655S28ZE

Applicable component levels

  • R23A PSY UI67390

       UP20/01/16 P F001

Fix is available

  • Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.

[{"Business Unit":{"code":"BU011","label":"Systems - zSystems software"}, "Product":{"code":"SG19M","label":"APARs - z/OS environment"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"23A","Edition":""}]

Document Information

Modified date:
04 February 2020