Configuring IBM Z Database Assistant

The configuration of IBM Z Database Assistant involves a script-driven sequence of interactive tasks. Ensure that you follow the step-by-step instructions and successfully complete each task.

t IBM-1047    T=on  -rw-r--r--   1 ZDBA   SPKGRP       262 May 22 10:14 .profile

To configure IBM Z Database Assistant:

1. Update the .profile file:
   • Add the following five lines, then modify JAVA_HOME, BASH_HOME, and their bin directories to point to the actual locations in your installation. Customize the INSTALL_DIR variable (for example: /usr/lpp/IBM/zdbav1r1) in the following and add to your .profile:

     
     export INSTALL_DIR=/usr/lpp/IBM/zdbav1r1               #Note: Customize this directory for your environment
     export JAVA_HOME=/java21/J21.0_64/                     #Note: This is your Java installation path
     export BASH_HOME=$INSTALL_DIR/bash                     #Note: Bash is provided by ZDBA in this directory
     export PATH=$JAVA_HOME/bin:$BASH_HOME/bin:$PATH
     export _BPXK_AUTOCVT=ON

   Note: If the above export statements were not previously specified, source the .profile file using ". ~/.profile" (alternatively, log out and log back in again).
2. Run the script to configure IBM Z Database Assistant:
   1. Customize and run the job your.sampjcl.pds(AURGMSID) to assign IBM Z Database Assistant metadata Db2® table privileges to the ID running the configuration script.
   2. In a bash session, change to the $INSTALL_DIR/configuration/scripts directory and execute the configuration script by issuing the following command:

      ./config.sh -a deploy

      Note: By default, the config.sh script connects to the metadata Db2 using a PassTicket. If the user running config.sh is not authorized to generate PassTickets (such as when PassTicket generation is restricted to protected IDs only), you can run the config.sh script using password authentication by specifying the metadata Db2 user ID and password. Alternatively, you can create an ID that is a surrogate of the protected ID and run config.sh with that ID. For example:

      ./config.sh -a deploy --password [password | passticket]

      Note: Write authority on the IBM Z Database Assistant configuration directory (CONFIG_DIR) is required in order to run the config.sh script.
      Note:

      IBM Z Database Assistant includes the JDBC driver that encrypts the user ID and password by default. Decrypting the user ID and password requires a fully configured ICSF with an available Cryptographic Express Coprocessor.

      If a Cryptographic Express Coprocessor is not available in your environment, when running the config.sh script, add the following additional property (when prompted):

      securityMechanism=3;

      This tells the JDBC driver to pass the user ID and password in the clear, which removes the requirement for ICSF.

   3. For each prompt, respond by entering the requested information or accepting the default:

   Table 1. Information for which you are prompted by the IBM Z Database Assistant configuration script.

   Requested information	Example
   Enter the IBM Z Database Assistant configuration path Note: The "configuration path" refers to the IBM Z Database Assistant home directory.	/lpar/zdba/configuration
   Confirm or enter the JAVA_HOME path.	/java21/J21.0_64
   Enter the time zone of the system running IBM Z Database Assistant services. Note: The value must be in a valid POSIX format.	EST5EDT,M3.2.0/2:00:00,M11.1.0/2:00:00 for New York, New York PST8PDT,M3.2.0/2:00:00,M11.1.0/2:00:00 for Los Angeles, CA MST7 for Phoenix, AZ BST0GMT,M3.5.0/1:00:00,M10.5.0/2:00:00 for London, UK
   Enter the user ID of key ring owner.	OMVSKERN
   Enter the key ring name.	ZDBARING
   Enter the Personal Certificate label.	ZDBA Personal Cert
   Are you using a third-party root certificate authority (CA) to sign the ZDBA personal certificate (for example, GoDaddy or DigiCert)? Note: If you used a CA certificate created by RACF to sign the personal certificate, answer "No".	Yes or No
   Enter the system-specific IP address where IBM Z Database Assistant is running.
   Enter the IBM Z Database Assistant user interface port.	7000
   Enter the IBM Z Database Assistant Liberty port.	7001
   Enter the local Spark port number to use or press Enter to use a random port.	7002
   Enter the maximum port retry attempts. Spark tries a range of ports from the start port to port + maxRetries. Press Enter to accept the default value of 4.	4
   Are you enabling (or have you already enabled) IBM watsonx Assistant for Z (WXAZ) for IBM Z Database Assistant? Note: If your IBM watsonx Assistant™ for Z environment is not yet ready and you have not installed the IBM Z Database Assistant agents yet, you can skip this step by specifying No for this option. When your environment is ready, you can use the following to add the agentic functionality: ./config.sh -a agent	Yes or No
   Enter the WXAZ hostname or IP address.	9.9.9.9
   Enter the WXAZ API service port.	9999
   Enter the WXAZ MCP server hostname or IP address.
   Enter the WXAZ MCP server port.
   Enter the metadata Scheduler ID.	ZDBASCH
   Enter the metadata Db2 GENERICLU/IPNAME for a data sharing environment or LUNAME/IPNAME for a non-data sharing environment. Note: If both are defined, enter the IPNAME.	APPLDB1A
   Enter the hostname or IP address for the Db2 metadata connection.	db1a.company.com
   Enter the user ID to be used for password authentication:	zdba
   Enter the password associated with the ID zdba.	<zdba_password>
   Enter the metadata Db2 GENERICLU/IPNAME (datasharing) or LU name (non-datasharing).	APPLDB1A
   Enter the hostname or IP address of the metadata Db2 system.	db1a.company.com
   Enter the Db2 metadata connection TCPIP or SECPORT port.	446
   Enter the Db2 metadata connection location name.	DB1A
   (Optional) Enter any additional connection properties for the Db2 metadata connection.	ClientApplicationInformation=ZDBA_APP_UI7000;
   Enter the Db2 metadata schema name.	ZDBA7100
   Do you want to modify the IBM Z Database Assistant job name prefix where the default is ZDBA?	Yes or No
   Enter a 1- to 4-character prefix for IBM Z Database Assistant job names.	ZDBA

   Note: You can choose to specify the starting Spark port number as well as the size of the range of Spark ports in the $CONFIG_DIR/config/assessconfig.json file. See Changing the ZDBA Spark settings for instructions.

   Note: You will only see this prompt if you used the password option to invoke the script.

   Note: The password text you enter will not be displayed.

   If the configuration is successful, the message "IBM Z Database Assistant configuration completed" will be displayed.

   Alternatively, you can add the above configuration details to an INI file and pass this file to IBM Z Database Assistant. For example:

   ./config.sh -a deploy -f /path/to/deploy.ini

   Note: The option to use password authentication is not available when running the installation using an INI file.

   Sample INI file contents:

   [environment]
   ; Specify the path for Java home directory
   java.home = /usr/lpp/java/java21/J21.0_64
   ; Specify the POSIX format time zone of the system running ZDBA services
   ; Examples:
   ;  PST8PDT,M3.2.0/2:00:00,M11.1.0/2:00:00 - Los Angeles
   ;  EST5EDT,M3.2.0/2:00:00,M11.1.0/2:00:00 - New York
   ;  GMT0BST,M3.5.0/1,M10.5.0 - London (UK)
   ;  ART3 - Sao Paulo (Brazil)
   ;  CET-1CEST,M3.5.0,M10.5.0/3 - Germany (Berlin)
   ;  IST-5:30 - India (Kolkata)
   ;  CST-8 - China (Shanghai):
   timezone = PST8PDT,M3.2.0/2:00:00,M11.1.0/2:00:00
   
   [metadata]
   ; Specify the metadata connection scheduler ID
   schedulerID = ZDBAMSCH
   ; Specify the Db2 metadata connection location name
   location = STLEC1
   ; Specify the hostname or IP address of the metadata Db2 system
   host = db2.domain.com
   ; Specify the Db2 metadata connection TCPPORT or SECPORT
   port = 44444
   ; Specify the Db2 metadata connection GENERICLU/IPNAME (datasharing) or
   ;  LUNAME/IPNAME (non-datasharing).  Note: If both are defined,
   ;  use the IPNAME.
   applname = APPLNAME
   ; Specify the schema name for the metadata Db2
   schema = DSNML
   ; (Optional) Specify any additional connection properties for the Db2 metadata
   ;  connection by uncommenting the "additional.props = " line below.  If
   ;  multiple properties are needed, separate them with a semi-colon.
   ; Example: additional.props = clientUser=ZDBAUSER;sslConnection=true;
   ; If a crypotgraphic processor is not available, you will need the following:
   ;   additional.props = securityMechanism=3;
   ; If you are using the SECPORT of Db2, you will need the following:
   ;  additional.props = sslConnection=true;
   ;additional.props =
   
   [zdba]
   ; Specify the ZDBA configuration directory ( example: /lpar/zdba/configuration/directory )
   home = /lpar/zdba/configuration/directory
   ; Specify the system specific IP address for the system where
   ;  ZDBA is running
   host = 9.9.9.9
   ; Specify the ZDBA user interface port
   frontend.port = 7100
   ; Specify the ZDBA Liberty port
   server.port = 7101
   ; Specify the local Spark port number to use or specify 'random' to use a random
   ;  port
   spark.start.port = 7102
   ; Specify the port max retry attempts. This allows Spark to try a range of ports
   ;  from the start port specified to port + maxRetries. A small value (ex. 3) is
   ;  usually adequate, but if you plan to run several to many concurrent system
   ;  assessments across multiple Db2 datasharing groups, a larger value may be required.
   spark.max.retries = 4
   
   ; Specify the prefix for ZDBA job names (max four characters)
   job.prefix = ZDBA
   
   ; Below are ZDBA default started task name suffixes.
   node.start.suffix = ND
   node.stop.suffix = ND
   monitor.start.suffix = MTR
   monitor.stop.suffix = MTRP
   liberty.suffix = LBTY
   
   [keyring]
   ; Specify the user ID of key ring owner
   owner = OMVSKERN
   ; Specify the key ring name
   name = ZDBARING
   ; Specify the personal certificate label
   cert.name = ZDBA personal certificate label
   ; Are you using a third-party root Certificate Authority (CA) such as
   ;  GoDaddy or DigiCert to sign the ZDBA personal certificate?
   ; Note: if you used a CA certificate generated by RACF to sign the personal
   ;  certificate, please answer 'No'.)
   using.3rd.party.ca = No
   
   [agent]
   ; Are you using an agent for ZDBA?
   is.agent = Yes
   ; Specify the system specific hostname or IP address for the system where
   ;  the agent is running (only required when is.agent = Yes)
   host = 8.8.8.8
   ; Specify the agent port (only required when is.agent = Yes)
   port = 8888
   ; Specify the WXAZ MCP server hostname or IP address (only required when is.agent = Yes)
   mcp.host = 9.9.9.9
   ; Specify the WXAZ MCP server port (only required when is.agent = Yes)
   mcp.port = 9999