Setting up integrations to interact with z/OS

You can use IBM Z® Open Editor on your computer without connecting to a z/OS® system and download files manually by using an FTP command or similar method. However, you can augment the capabilities of IBM Z Open Editor and enjoy a seamless integration of z/OS with IBM® Remote System Explorer API (RSE API) or the Zowe open source project. The Zowe™ project provides great tools that work perfectly with the IBM Z Open Editor.

Note, that with Zowe Explorer 3.0 and Z Open Editor 5.0.0 some changes were introduced to the way this integration is configured that might require some migration from older versions. See the Getting started with Zowe Explorer v3.0 for an overview.

When using IBM Z Open Editor, you can choose how to interact with z/OS with regard to the following aspects:

Use RSE API or the Zowe default z/OSMF as the host component
Use the command line or graphical interface to interact with z/OS

Next, you can use the following client-side tools based on your decision:

Available host component	To use graphical interface, install...	To use command line, install...
RSE API	Zowe Explorer	Zowe CLI, and IBM RSE API Plug-in for Zowe CLI
z/OSMF	Zowe Explorer	Zowe CLI

Detailed information about these tools is as follows:

The Zowe Explorer VS Code extension (Zowe Explorer) provides you with graphical views to explore MVS, z/OS UNIX System Services, and JES remotely. When you install IBM Z Open Editor from the VS Code Marketplace into your VS Code, the latest version of the Zowe Explorer VS Code extension is automatically co-installed. For more information about its capabilities and usage, see Zowe Explorer in the VS Code Marketplace and Zowe Docs. To use Zowe Explorer with IBM Z Open Editor, see Using the Zowe Explorer views.
The IBM RSE API Plug-in for Zowe CLI (RSE CLI plug-in) enables remote interaction with z/OS through the command line using the RSE API, instead of the default z/OSMF interface provided by Zowe. To get started, see Installing IBM RSE API Plug-in for Zowe CLI. To use RSE API on your client, see Using RSE API in Zowe Explorer and Using RSE CLI plug-in commands.
Zowe CLI enables remote interaction with z/OS through the command line. After installation, as described in Installing Zowe CLI, you must create a Zowe CLI z/OSMF user profile to store your personal connection information. To use Zowe CLI with IBM Z Open Editor, see Using Zowe CLI z/OSMF commands.

Install Zowe CLI

The prerequisites to install Zowe CLI are as follows:

Client: Install Node.js version 20, or a later version
Host (select one or both):
- Configure z/OSMF if you plan to use Zowe CLI without RSE CLI plug-in
- Install and configure the IBM Remote System Explorer API if you plan to use Zowe CLI together with the RSE CLI plug-in to extend its capabilities. Version 1.1.6 or higher is the suggested RSE Rest API version.

You can install Zowe CLI using one of the methods below:

Follow the Zowe documentation on Installing Zowe CLI to install Zowe CLI from the Zowe.org website or the npmjs.com npm package registry.
Alternatively, you can get a certified IBM Zowe distribution from IBM Mainframe DEV. You can also purchase technical support for Zowe from IBM for this distribution.

Install IBM RSE API Plug-in for Zowe CLI

Prerequisites

Before you install IBM RSE API Plug-in for Zowe CLI on your development machine, you must install Zowe CLI v8.0.0 or later. For more information on how to install Zowe CLI, see Installing Zowe CLI.

Install the requisite IBM RSE API z/OS host component

Confirm with your system administrator that the following host components are installed and configured on the z/OS host system:

The host component of z/OS Explorer 3.3 or 3.4, which is the prerequisite of the RSE API host component.
The RSE API host component version 1.1.6 or higher is suggested, which provides a collection of REST APIs that allow a client to work with various components on the z/OS host system, including MVS data sets, z/OS UNIX files and commands, JES jobs, and more.

For information on how to install and configure the RSE API host component, see RSE API documentation.

Note: Even if your system administrator has previously installed RSE on your z/OS, an update is needed to get the capabilities described here.

Install the IBM RSE API Plug-in for Zowe CLI

After you install and configure the prerequisites and the host component, follow these steps to install the RSE CLI plug-in. You can choose to download the plug-in from

IBM as a code-signed archive file for local and even air-gapped installations, that does not require an internet connection to public domains.
a public repository at npmjs.com for a more convenient online installation. This repository is the same from which you might have installed Zowe CLI following instructions from the Zowe docs.

Option 1: Download install package from IBM

Navigate to the Mainframe DEV website.
In the IBM Z VS Code Components section find the IBM Developer for z/OS on VS Code row. If you are an ADFz customer find the row IBM Application Delivery Foundation for z/OS (ADFz) on VS Code.
Click the link icon in the column Download Client.
You are redirected to the Software License Agreement page. Review the License Agreement and click I Agree. It prompts you to save or open a compressed .zip file in your browser.
Save the compressed .zip file to your workstation.
Extract the compressed .zip file on your workstation. You find various files in the archive, including two different RSE API Plugin for Zowe CLI .tgz files, ibm-rse-api-for-zowe-cli-v.r.m.tgz and ibm-rse-api-for-zowe-cli-airgap-v.r.m.tgz. The ibm-rse-api-for-zowe-cli-airgap-v.r.m.tgz package has all dependencies included in the bundle for environments without network access.
Optionally, follow the instructions in the included README.txt file to verify the code signatures to ensure the files were signed against a trusted IBM certificate.
Install the desired RSE CLI plug-in variant by entering the following command in the terminal:
```
zowe plugins install path/to/download/ibm-rse-api-for-zowe-cli-pkg.tgz
```
where path/to/download/ibm-rse-api-for-zowe-cli-pkg.tgz should be defined with your own file path to install the package.

Option 2: Install from npmjs.com

Install the RSE CLI plug-in by entering the following command in the terminal:
```
zowe plugins install @ibm/rse-api-for-zowe-cli
```

Validate installation

If the installation was successful, you can see the following message printed in the terminal:

Installed plugin name = '@ibm/ibm-rse-api-for-zowe-cli'

_____ Validation results for plugin '@ibm/ibm-rse-api-for-zowe-cli' _____
This plugin was successfully validated. Enjoy the plugin.

Get help

After you install the RSE CLI plug-in, you can see all the command options of the plug-in by entering the command zowe rse --help into the terminal.

Update the IBM RSE API Plug-in for Zowe CLI

Update previous npmjs.com install

If the previous installation of the RSE CLI plug-in was from npmjs.com, run the following command to update to the latest version available on npmjs.com:

zowe plugins update @ibm/rse-api-for-zowe-cli

Update previous .tgz install

Uninstall the older version of RSE CLI plug-in:
- If the original .tgz file of the older version is still in the original location from the installation, run the following command.
```
zowe plugins uninstall @ibm/rse-api-for-zowe-cli
```
- If the original .tgz file is no longer in the original location from the installation, complete the following procedure:
  1. Use the file explorer to open the .zowe folder in the home directory.
  2. Within the .zowe directory, go to the plugins/installed/node_modules/@ibm directory and delete the rse-api-for-zowe-cli folder.
  3. Navigate to the .zowe/plugins directory, open the plugins.json file in edit mode and remove the @ibm/rse-api-for-zowe-cli section as shown below and save the file.
```
"@ibm/rse-api-for-zowe-cli": {
  "package": "@ibm/rse-api-for-zowe-cli",
  "registry": "installation/location",
  "version": "1.0.0"
}
```
Verify the uninstallation.
Run the command zowe plugins list. The list of plug-ins should no longer contain @ibm/rse-api-for-zowe-cli upon a successful uninstallation.
Delete rse_meta.yaml file from the .zowe/profiles/rse directory.
Install the new version of RSE CLI plug-in.
Refer back to Installing the IBM RSE API Plug-in for Zowe CLI to install the new .tgz download of IBM RSE API Plug-in for Zowe CLI.

Move from .tgz install to npmjs.com install

Follow step 1 - 3 of Update previous .tgz install.
Run command zowe plugins install @ibm/rse-api-for-zowe-cli, which pulls from npmjs.com.

Set log levels for IBM RSE CLI plug-in

To Set up log levels for the RSE CLI plug-in, follow the same method used to set Zowe CLI log levels, and logs are written to the log file location /.zowe/zowe/logs/zowe.log. You can set the log level to adjust the level of detail that is written to the log file.

Important! Setting the log level to TRACE or ALL may result in "sensitive" data being logged.

Environment Variable	Description	Values	Default
`ZOWE_APP_LOG_LEVEL`	Zowe CLI and RSE CLI plug-in logging level	Log4JS log levels (OFF, TRACE, DEBUG, INFO, WARN, ERROR, FATAL)	DEBUG

Authentication using Zowe

Manage credentials securely

Store username and password securely is Zowe CLI's default behavior. Upon installation of Zowe CLI, a file is created in the ~/.zowe/settings directory called imperative.json that holds the value of the Credential Manager to be used. By default this value is @zowe/cli.

Manage credentials unsecured

In some cases or environments the default Credential Manager is not supported. Zowe Explorer provides an option to disable secure credentials. We do not recommend disabling secure credentials unless your environment does not support it. To disable secure credentials set Zowe Explorer VS Code user setting zowe.security.secureCredentialsEnabled to false. Setting secureCredentialsEnabled to false updates ~/.zowe/settings/imperative.json like the example below:

{
  "overrides": {
    "CredentialManager": false
  }
}

Single sign-on support for IBM RSE CLI plug-in

RSE CLI plug-in has single sign-on (SSO) support using JSON Web Tokens (JWT) that are issued by the RSE API host component to the RSE profile. If the RSE API host component is configured and registered with the Zowe API Mediation Layer (API ML), the RSE CLI plug-in also supports SSO using a JWT that is issued to a Zowe CLI base profile by the API ML. The JWTs can be used for authentication with the RSE API host component through command line operations as well as operations done within IBM Z Open Editor and Zowe Explorer's z/OS integrations. Learn more about how to obtain JSON Web Tokens (JWT) from the RSE API host component with the RSE CLI plug-in or through Zowe Explorer.

Example Zowe configurations

Multi-Factor Authentication (MFA) support

Zowe Profiles supported by Zowe CLI, the RSE CLI plug-in, IBM Z Open Editor, and Zowe Explorer can be used with Multi-Factor Authentication (MFA). To set it up correctly, it's important to understand how MFA functions at your site. Typically, you use an authenticator app to generate a temporary code, which is appended to the password in the format passord:mfaToken or used as a replacement for the password. The system administrator must ensure that the application is properly configured for Zowe users. MFA authentication can be applied in two scenarios, depending on the lifespan of the MFA token.

MFA tokens with a longer lifespan can be stored as a password for the duration of the session.
Short-lived MFA tokens can be used to log in and retrieve a JSON Web Token (JWT) for continued authentication.

Zowe z/OSMF profile types require an API ML connection to support MFA when using short-lived tokens that require a login action. Zowe RSE profile types support both scenarios: the API ML route if RSE API host components are registered or through a direct RSE API connection.

NOTE Cloud environments with autostore: false in the Zowe Team configuration, in combination with a disabled Zowe Explorer credentials manager setting, experience requests that do not work as the token must be persisted.

More information regarding MFA support for Zowe CLI and API Meditation Layer.

Certificate Authentication support

Zowe z/OSMF profiles used with Zowe CLI, IBM Z Open Editor, and Zowe Explorer support certificate authentication either through a direct connection to z/OSMF Rest APIs or by logging in to the Zowe API ML. For more information, refer to the certificate support with the Zowe API ML.

The IBM Knowledge Center includes documentation for Configuring the z/OSMF server certificate and key ring. Additionally, there is a blog post from the Zowe community on Medium.com that explains both server and client setup of z/OSMF server certificates.

Zowe CLI supports certificates to authenticate with z/OSMF in two ways. TLegacy support requires you to split the certificate into a .crt and .key file, and then specify their paths in the Team Configuration file. The latest support, introduced in Zowe v3.5.0, enables you to import the certificate into the operating system Certificate Manager and reference it in the Team Configuration file by using the Common Name (CN). The new secure certificate support is available only with Zowe CLI v8.32.0 or later, included in Zowe v3.5.0. Future releases plan to extend this support to other Zowe components such as Zowe Explorer and extenders.

For more information, refer to profile setup for certificate support

Proxy support

RSE CLI plug-in supports proxy servers using environment variables and VS Code proxy settings. If using rse profiles for both CLI and in VS Code setting the environment variables are used in the same manner across both platforms. These environment variables include HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. If using the rse profile in just the VS Code environment, VS Code proxy settings can be used in place of environment variables. More information regarding setting up proxy servers with Zowe in the Zowe Explorer wiki for Working with Proxy Servers.

Zowe Explorer requires the http.proxySupport setting to be set to on for other proxy settings to be recognized. VS Code proxy settings recognized by Zowe Explorer include http.noProxy, http.proxy, http.proxyAuthorization, and http.proxyStrictSSL.

Known Issues

If you encounter any issues or concerns during installation or while you use the RSE CLI plug-in, refer to the known issues documentation for the RSE CLI plug-in.