A fix is available
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":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SG19M","label":"APARs - z\/OS environment"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"23A","Edition":"","Line of Business":{"code":"","label":""}}]
Document Information
Modified date:
04 February 2020