Setting up for IBM Z Open Debug

Before you can connect to a z/OS® system and start debugging, configure for IBM Z® Open Debug.

Defining a Z Open Debug connection using Zowe

To connect to a z/OS system, specify a zOpenDebug connection profile with connections details as below in the Zowe team configuration file.

    "zOpenDebug": {
        "type": "zOpenDebug",
        "properties": {
            "dpsPort": 8143,
            "dpsContextRoot": "api/v1",
            "dpsSecured": true,                        
            "host": "yourZmachine.yourCompany.com",
            "rdsPort": 8002,
            "rdsSecured": true,
            "rejectUnauthorized": false,
            "uuid": "eb56ad6a-38b8-4e2f-bad3-10fc1530ea9f"
            },
        "secure": [
            "user",
            "password"
        ] 
    },

The following attributes are supported in the zOpenDebug connection profile:

authenticationType: Specify the port of the Debug Profile Service. Supports token and basic.
tokenValue: The JWT token when authenticated with Debug Profile Service. Make sure this is stored in the profile's secure properties array.
dpsPort: Specify the port of the Debug Profile Service on the remote z/OS system. For a secured connection, ensure that a secure port is specified.
dpsContextRoot: Specify the context root of the Debug Profile Service on the remote z/OS system.
dpsSecured: Enable a secure connection.
host: Specify the hostname of the remote z/OS system.
rdsPort: Specify the port of the Remote Debug Service on the remote z/OS system. For a secured connection, ensure that a secure port is specified.
rdsSecured: Enable a secure connection.
rejectUnauthorized: Specify whether to reject an unauthorized connection.
uuid: A special internal attribute that is generated dynamically when you create the connection profile.
secure: Specify that secure connections should be used.
user: Specify the user ID to be used for connection.
password: Specify the password to be used for authentication when you connect to remote z/OS system. By default, a password prompt is displayed the first time you connect to the remote system.

You can also use the connection details from a base profile, create multiple connection profiles, nest the profile inside another profile, and share the profile with others. For more information, see the Zowe Docs.

Configuring the preferences

You can specify other preferences in Settings > Extensions > IBM Z Open Debug or in the setting.json file.

Table 1. Settings for IBM Z Open Debug
Field name in Settings	Property in settings.json	Description
Debug Profile Service: Api Log	zopendebug.debugProfileService.apiLog	Enable diagnostic logging of the Debug Profile Service. The logs can be found in the Output panel. Select IBM Z Open Debug from the list to filter out relevant log.
Profile View: Show Welcome	zopendebug.profileView.showWelcome	Show the welcome page to the Debug Profile Editor.
Logger: Log Level	zopendebug.logger.logLevel	Select the level of logging in the application.
Profile View: Show Generic Profile Warning	zopendebug.profileView.showGenericProfileWarning	Show warnings in the Debug Profile Editor when you try to activate a generic debug profile.

Managing a connection

After you create a connection profile in the Zowe team configuration file as described in Defining a Z Open Debug connection using Zowe, add them to the z/OS Debugger Profiles view by selecting the Add existing Connection button, or by clicking the + icon in the view.

Multiple connection profiles can be created for you to switch among the connections more easily.

You can manage your connection profile with the Manage Profile context menu item. This will open a quick-pick with the following options:

Add/Update Credentials - Adds or updates user credentials that will be saved in the user and password attributes in the connection profile.
Log In - Authenticates with Debug Profile Service using the authentication type specified in the authenticationType attribute. User will be prompted for credentials if there are none already saved in the connection profile.
Edit Profile - Opens up the Zowe Team Configuration file allowing the user to edit their connection profile.
Hide Profile - Removes the connection profile from the z/OS Debugger Profiles View, but keeps the profile definition in the Zowe Team Configuration file.
Delete Profile - Removes the connection profile from the z/OS Debugger Profiles View, and deletes the profile definition in the Zowe Team Configuration file.

You can edit in the Zowe team configuration file directly to add, modify, or delete the connection profile. Alternatively, you can right-click the connection and select Edit Connection Profile or Delete Connection Profile from menu.

The first time that you connect to the host, you are prompted to enter your user ID and password. The connection details are displayed under the Properties node or when you hover over the connection node. You can later update the connection credentials by right-clicking the connection and select Update Connection Credentials from menu.

Configuring launch.json

To configure launch.json for IBM Z Open Debug, see the supported attributes in Starting an interactive debug session with IBM Z Open Debug and Listing parked z/OS Debugger debug sessions on a z/OS host.

Starting from Z Open Debug 4.0, the connection details are specified in a zOpenDebug connection profile in the Zowe team configuration file instead of the launch.json. In the launch.json, specify the connection attribute as below to use the zOpenDebug connection profile:

"connection": { 
            "type": "zowe", "name": "zOpenDebug"
    },

Importing a self-signed certificate for Debug Profile Service

Z Open Debug uses the Debug Profile Service API to manage debug profiles. This REST API is secured with a certificate. If the certificate is self-signed, you need to install the certificate to the operating system to establish a secured communication.

Notes:

A self-signed certificate is always used for Wazi for Dev Spaces in the OpenShift® cloud environment.
You can specify rejectUnauthorized: false in your Zowe connection profile. However, this configuration ignores all SSL errors and is less secure.

Before you establish a secured connection, ensure that your system programmer created a certificate for Debug Profile Service as described in Enabling secure communication and you are connected to the remote z/OS system with a secured port specified and the secured connection enabled.

Obtain the certificate directly from the systems programmer, or follow the steps below to obtain the certificate with a browser:
1. Enter {host_name}:{dps_port}/api/v1/profile/dtcn in the address bar of a browser. A warning icon that indicates insecure connection is displayed in the address bar.
2. Click the warning icon to download or export the certificate.
  Note: After you import the certificate into the certificate store of the operating system, the original name instead of the name you specified when you exported the certificate is displayed.
Optionally, you can specify rejectUnauthorized: false in the Zowe connection profile. However, this ignore all SSL errors and is less secure.
Import the self-signed certificate to your operating system.
You can import the certificate into Trusted Root Certification Authorities on Windows or Keychain Access on macOS directly, or use Google Chrome for any operating systems or Internet Explorer for Windows.
Google Chrome for Windows:
1. Select Settings > Privacy and security > Manage certificates.
2. In the Certificates window, open the Trusted Root Certification Authorities tab and select Import. The Certificate Import Wizard opens.
3. In the Certificate Import Wizard, browse to select the certificate. You might need to choose All Files (*.*) to display all file types.
4. Click Finish to complete importing the certificate.
5. In the Certificates window, select Advanced to open the Advanced Options window and ensure that Client Authentication is selected.
Google Chrome for macOS:
1. Select Settings > Privacy and security > Manage certificates.
2. In Keychain Access, import the certificate.
3. Double-click the imported certificate to set the fields to Always Trust.
Internet Explorer for Windows:
1. Select Tools > Internet Options.
2. On the Content tab of the Internet Options window, select Certificates to open the Certificates window.
3. In the Certificates window, open the Trusted Root Certification Authorities tab and select Import. The Certificate Import Wizard opens.
4. In the Certificate Import Wizard, browse to select the certificate. You might need to choose All Files (*.*) to display all file types.
5. Click Finish to complete importing the certificate.
6. In the Certificates window, select Advanced to open the Advanced Options window and ensure that Client Authentication is selected.