Zowe Version 2.

0 Documentation
Table of contents:
Zowe overview
Zowe overview
Zowe demo video
Component overview
Zowe Application Framework
API Mediation Layer
Zowe CLI
Zowe Explorer
Zowe Client Software Development Kits (SDKs)
Zowe Launcher
Zowe Mobile - Incubator
ZEBRA (Zowe Embedded Browser for RMF/SMF and APIs) - Incubator
Zowe Workflow wiZard - Incubator
Zowe Third-Party Software Requirements and Bill of Materials
Zowe architecture
Zowe architecture
Zowe architecture with high availability enablement on Sysplex
Zowe architecture when running in Kubernetes cluster
App Server
ZSS
API Gateway
API Catalog
API Discovery
Caching service
Desktop Apps
File API and JES API
Cross Memory server
FAQ: Zowe and components
FAQ: Zowe and components
Zowe FAQ
What is Zowe?
Who is the target audience for using Zowe?
What language is Zowe written in?
What is the licensing for Zowe?
Why is Zowe licensed using EPL2.0?
 What are some examples of how Zowe technology might be used by z/OS products and
applications?
What is the best way to get started with Zowe?
What are the prerequisites for Zowe?
What's the difference between using Zowe with or without Docker?
Is the Zowe CLI packaged within the Zowe Docker download?
Does ZOWE support z/OS ZIIP processors?
How is access security managed on z/OS?
How is access to the Zowe open source managed?
How do I get involved in the open source development?
When will Zowe be completed?
Can I try Zowe without a z/OS instance?
Zowe CLI FAQ
Why might I use Zowe CLI versus a traditional ISPF interface to perform mainframe tasks?
With what tools is Zowe CLI compatible?
Where can I use the CLI?
Which method should I use to install Zowe CLI?
How can I get Zowe CLI to run faster?
How can I manage profiles for my projects and teams?
How can I get help with using Zowe CLI?
How can I use Zowe CLI to automate mainframe actions?
How can I contribute to Zowe CLI?
Zowe Explorer FAQ
Why might I use Zowe Explorer versus a traditional ISPF interface to perform mainframe tasks?
How can I get started with Zowe Explorer?
Where can I use Zowe Explorer?
How do I get help with using Zowe Explorer?
How can I use Secure Credential Storage for Zowe Explorer?
What types of profiles can I create for Zowe Explorer?
How can I use FTP as my back-end service for Zowe Explorer?
How can I contribute to Zowe Explorer?
FAQ: Zowe V2
FAQ: Zowe V2
Where can I find the V1 and V2 LTS conformance criteria?
Whats the difference between "server.json" and "example-zowe.yaml"?
What are the new default ports?
How do I access Zowe through the API Mediation Layer in V2?
What new frameworks are supported in V2?
 Why aren't the explorers appearing on my desktop anymore?
Version 2.0.0 (April 2022)
Version 2.0.0 (April 2022)
Breaking changes
Zowe installation
API Mediation Layer
Zowe Application Framework
Zowe CLI
New features and enhancements
Zowe installation
Zowe API Mediation Layer
Zowe Application Framework
Zowe CLI
Zowe Explorer
Bug fixes
Zowe API Mediation Layer
Zowe Application Framework
Conformance and release compatibility
Backward compatibility
Forward compatibility
Conformance compatibility
Zowe V2 office hours videos
Zowe V2 office hours videos
Office hours for Zowe extenders
General information
Zowe component updates
Installation and V2 conformance
Office hours for Zowe consumers
Zowe CLI quick start
Zowe CLI quick start
Installing
Software Requirements
Installing Zowe CLI core from public npm
Installing CLI plug-ins
Issuing your first commands
Listing all data sets under a high-level qualifier (HLQ)
Downloading a partitioned data-set (PDS) member to local file
Team profiles
 Using profiles
Profile types
Creating zosmf profiles
Using zosmf profiles
Writing scripts
Example:
Next steps
Migrating Zowe server component from V1 to V2
Migrating Zowe server component from V1 to V2
Component manifest
Lifecycle scripts
Environment variables
Packaging one component deliverable for both Zowe v1 and v2
Zowe learning resources
Zowe learning resources
Blogs
Videos
Webinars
Community
Training
Overview
Overview
Installation roadmap
Installation roadmap
Stage 1: Plan and prepare
Stage 2: Install the Zowe z/OS runtime
Stage 3: Configure the Zowe z/OS runtime
Looking for troubleshooting help?
Planning the installation
Planning the installation
Topology of the Zowe z/OS launch process
Runtime directory
z/OS Data sets used by Zowe
Zowe configuration file
Workspace directory
Log directory
Keystore directory
Extension directory
UNIX System Services considerations for Zowe
UNIX System Services considerations for Zowe
What is USS?
Setting up USS for the first time
Language environment
OMVS segment
Address space region size
System requirements
System requirements
z/OS system requirements
z/OS
Node.js
Java
z/OSMF (Optional)
User ID requirements
ZWESVUSR
ZWESIUSR
ZWEADMIN
zowe_user
Network requirements
Zowe Containers requirements
Zowe Desktop requirements (client PC)
Feature requirements
Multi-Factor Authentication (MFA)
Single Sign-On (SSO)
Memory requirements
Installing Node.js on z/OS
Installing Node.js on z/OS
Supported Node.js versions
How to obtain IBM SDK for Node.js - z/OS
Hardware and software prerequisites
Installing the PAX edition of Node.js - z/OS
Installing the SMP/E edition of Node.js - z/OS
Configuring z/OSMF
Configuring z/OSMF
z/OS requirements for z/OSMF configuration
Configuring z/OSMF
z/OSMF REST services for the Zowe CLI
 Configuration of z/OSMF to properly work with API ML
Configuring z/OSMF Lite (for non-production use)
Configuring z/OSMF Lite (for non-production use)
Introduction
Assumptions
Software Requirements
Minimum Java level
WebSphere® Liberty profile (z/OSMF V2R3 and later)
System settings
Web browser
Creating a z/OSMF nucleus on your system
Running job IZUNUSEC to create security
Running job IZUMKFS to create the z/OSMF user file system
Copying the IBM procedures into JES PROCLIB
Starting the z/OSMF server
Accessing the z/OSMF Welcome page
Mounting the z/OSMF user file system at IPL time
Adding the required REST services
Enabling the z/OSMF JOB REST services
Enabling the TSO REST services
Enabling the z/OSMF data set and file REST services
Enabling the z/OSMF Workflow REST services and Workflows task UI
Troubleshooting problems
Common problems and scenarios
Tools and techniques for troubleshooting
Appendix A. Creating an IZUPRMxx parmlib member
Appendix B. Modifying IZUSVR1 settings
Appendix C. Adding more users to z/OSMF
Before you Begin
Procedure
Results
Installing Zowe runtime from a convenience build
Installing Zowe runtime from a convenience build
Introduction
Step 1: Obtain the convenience build
Step 2: Transfer the convenience build to USS and expand it
Step 3: (Optional) Add the zwe command to your PATH
Step 4: Copy the zowe.yaml configuration file to preferred location
 Step 5: Install the MVS data sets
About the MVS data sets
Procedure
Next steps
Installing Zowe SMP/E
Installing Zowe SMP/E
Introduction
Zowe description
Zowe FMIDs
Program materials
Basic machine-readable material
Program source materials
Publications useful during installation
Program support
Statement of support procedures
Program and service level information
Program level information
Service level information
Installation requirements and considerations
Driving system requirements
Target system requirements
FMIDs deleted
Installation instructions
SMP/E considerations for installing Zowe
SMP/E options subentry values
Overview of the installation steps
Download the Zowe SMP/E package>P>
Allocate file system to hold the download package
Upload the download package to the host
Extract and expand the compressed SMPMCS and RELFILEs
Sample installation jobs
Create SMP/E environment (Optional)
Perform SMP/E RECEIVE
Allocate SMP/E target and distributions libraries
Allocate, create and mount ZSF files (Optional)
Allocate z/OS UNIX paths
Create DDDEF entries
Perform SMP/E APPLY
 Perform SMP/E ACCEPT
Run REPORT CROSSZONE
Cleaning up obsolete data sets, paths, and DDDEFs
Activating Zowe
File system execution
Zowe customization
Installing Zowe SMP/E build with z/OSMF workflow
Installing Zowe SMP/E build with z/OSMF workflow
Activating Zowe
File system execution
Zowe customization
Installing Zowe from a Portable Software Instance
Installing Zowe from a Portable Software Instance
Prerequisites
Procedure
Address z/OSMF Requirements
Address z/OSMF Requirements
Acquire a z/OSMF Portable Software Instance
Acquire a z/OSMF Portable Software Instance
Download the Portable Software Instance from Zowe Downloads
Register Portable Software Instance in z/OSMF
Install Product Software Using z/OSMF Deployments
Install Product Software Using z/OSMF Deployments
Initializing the z/OS system
Initializing the z/OS system
About the zwe init command
Procedure
Next steps
Initializing Zowe custom data sets
Initializing Zowe custom data sets
Introduction
Procedure
Results
Initialize Zowe security configurations
Initialize Zowe security configurations
Configuring with zwe init security command
Configuring with ZWESECUR JCL
Undo security configurations
 Next steps
Configuring the z/OS system for Zowe
Configuring the z/OS system for Zowe
Configure an ICSF cryptographic services environment
Configure security environment switching
Configure address space job naming
Configure multi-user address space (for TSS only)
Configure user IDs and groups for the Zowe started tasks
Configure ZWESLSTC to run Zowe high availability instances under ZWESVUSR user ID
Configure the cross memory server for SAF
Configure main Zowe server to use identity mapping
Using RACF
Using ACF2
Using TSS
Configure signed SAF Identity tokens (IDT)
Granting users permission to access z/OSMF
Granting users permission to access z/OSMF
APF authorize load libraries
APF authorize load libraries
Configuring PKCS12 certificates
Configuring PKCS12 certificates
Use a PKCS12 certificate
Create a self signed PKCS12 certificate
Manually import a certificate authority into a web browser
Configuring JCERACFS certificates in a key ring
Configuring JCERACFS certificates in a key ring
Create a certificate authority and use it to self sign a certificate
Create a self signed JCERACFKS certificate
Set up Zowe certificates using workflows
Set up Zowe certificates using workflows
Creating VSAM caching service datasets
Creating VSAM caching service datasets
Using zwe init vsam command
Installing Zowe main started tasks
Installing Zowe main started tasks
Installing and configuring the Zowe cross memory server (ZWESISTC)
Installing and configuring the Zowe cross memory server (ZWESISTC)
PDS sample library and PDSE load library
 Load module
APF authorize
Key 4 non-swappable
PARMLIB
PROCLIB
SAF configuration
Summary of cross memory server installation
Starting and stopping the cross memory server on z/OS
Zowe auxiliary service
When to configure the auxiliary service
Installing the auxiliary service
Zowe Auxiliary Address space
Zowe Auxiliary Address space
Configure Zowe with z/OSMF Workflows
Configure Zowe with z/OSMF Workflows
Configure the Zowe instance directory
Register and execute workflow in the z/OSMF web interface
Overview
Overview
Enable high availability when Zowe runs in Sysplex
Known limitations
Enable high availability when Zowe runs in Kubernetes
Configuring Sysplex for high availability
Configuring Sysplex for high availability
Sysplex environment requirements
Configuring Sysplex Distributor
Configuring z/OSMF for high availability in Sysplex
Configuring z/OSMF for high availability in Sysplex
Sysplex environment requirements
Setting up z/OSMF nucleus
Requirements of z/OSMF HA parmlib member in Sysplex
Configuring z/OSMF for high availability
Configuring the Caching Service for HA
Configuring the Caching Service for HA
Starting and stopping Zowe
Starting and stopping Zowe
Starting and stopping the cross memory server ZWESISTC on z/OS
Starting and stopping the cross memory auxiliary server ZWESASTC on z/OS
 Starting and stopping Zowe main server ZWESLSTC on z/OS with zwe server command
Starting and stopping Zowe main server ZWESLSTC on z/OS manually
Stopping and starting a Zowe component without restarting Zowe main server
Verifying Zowe installation on z/OS
Verifying Zowe installation on z/OS
Verifying Zowe Application Framework installation
Verifying API Mediation installation
Verifying z/OS Services installation
Introduction
Introduction
Known limitations
Prerequisites
Prerequisites
Kubernetes cluster
kubectl tool
Downloading and installing
Downloading and installing
Downloading
Downloading configuration samples
Downloading container images
Installing
Upgrading
Configuring
Configuring
1. Create namespace and service account
2. Create Persistent Volume Claim (PVC)
3. Create and modify ConfigMaps and Secrets
4. Expose API Mediation Layer components
4a. Create service
4b. Create Ingress (Bare-metal)
4c. Create Route (OpenShift)
Customizing or manually creating ConfigMaps and Secrets
PodDisruptionBudget
HorizontalPodAutoscaler
Kubernetes v1.21+
Starting, stopping, and monitoring
Starting, stopping, and monitoring
Starting Zowe containers
 Port forwarding (for minikube only)
Verifying Zowe containers
Monitoring Zowe containers
Monitoring Zowe containers via UI
Monitoring Zowe containers via CLI
Stopping, pausing or removing Zowe containers
Installation checklist
Installation checklist
Addressing the prerequisites
Installing Zowe CLI
Configuring Zowe CLI
System requirements
System requirements
Client-side requirements
Host-side requirements
Free disk space
Installing Zowe CLI
Installing Zowe CLI
Installation guidelines
Installation notes
Prerequisites
Prerequisite notes
Install Zowe CLI from npm
Install Zowe CLI from a local package
Configuring Secure Credential Store on headless Linux operating systems
Configuring Secure Credential Store on headless Linux operating systems
Headless Linux requirements
Unlocking the keyring manually
Unlocking the keyring automatically
Configuring z/Linux
Configure Zowe CLI on operating systems where the Secure Credential Store is not available
Configure Zowe CLI on operating systems where the Secure Credential Store is not available
V1 profiles
Team configuration
Installing Zowe CLI with Node.js 16 on Windows
Installing Zowe CLI with Node.js 16 on Windows
Additional Considerations
Install CLI from Online Registry Via Proxy
Install CLI from Online Registry Via Proxy
Updating Zowe CLI
Updating Zowe CLI
Updating to the Zowe CLI V2 Long-term Support (v2-lts) version
Identify the currently installed version of Zowe CLI
Identify the currently installed versions of Zowe CLI plug-ins
Update Zowe CLI from the online registry
Update or revert Zowe CLI to a specific version
Update Zowe CLI from a local package
Uninstalling Zowe CLI
Uninstalling Zowe CLI
Visual Studio Code (VS Code) Extension for Zowe
Visual Studio Code (VS Code) Extension for Zowe
Software Requirements
Profile notes:
Installing
Configuration
Relevant Information
Zowe Explorer Profiles
Zowe Explorer Profiles
Configuring team profiles
Creating team configuration files
Managing profiles
Sample profile configuration
Working with Zowe Explorer profiles
Validating profiles
Using base profiles and tokens with existing profiles
Accessing services through API ML using SSO
Logging in to the Authentication Service
Configuring Zowe Application Framework
Configuring Zowe Application Framework
Accessing the App Server
Accessing the Desktop
Accessing ZSS
Configuration file
app-server configuration
zss configuration
Environment variables
 Configuring the framework as a Mediation Layer client
Setting up terminal app plugins
Setting up the TN3270 mainframe terminal app plugin
Setting up the VT Terminal app plugin
Network configuration
HTTPS
HTTP
Configuration Directories
Old defaults
App plugin configuration
Logging configuration
Enabling tracing
Log files
ZSS configuration
ZSS 64 or 31 bit modes
Using AT-TLS in the App Framework
Creating AT-TLS certificates and keyring using RACF
Defining the AT-TLS rule
Using multiple ZIS instances
Controlling access to apps
Enabling RBAC
Controlling app access for all users
Controlling app access for individual users
Controlling access to dataservices
Defining the RACF ZOWE class
Creating authorization profiles
Creating generic authorization profiles
Configuring basic authorization
Endpoint URL length limitations
Multi-factor authentication configuration
Session duration and expiration
Configuration
Administering the servers and plugins using an API
Configuring Zowe CLI environment variables
Configuring Zowe CLI environment variables
Setting the CLI home directory
Setting CLI log levels
Setting CLI daemon mode properties
Configuring the Zowe APIs
Configuring the Zowe APIs
Advanced Gateway features configuration
Advanced Gateway features configuration
SAF as an Authentication provider
Enable JWT token refresh endpoint
Change password with SAF provider
Change password with z/OSMF provider
Gateway retry policy
Gateway client certificate authentication
Gateway timeouts
CORS handling
Encoded slashes
Connection limits
Routed instance header
Distributed load balancer cache
Replace or remove the Catalog with another service
API Mediation Layer as a standalone component
SAF Resource Checking
Checking providers
Discovery Service configuration parameters
Discovery Service configuration parameters
Zowe runtime configuration parameters
API ML configuration
Eureka configuration
API Gateway configuration parameters
API Gateway configuration parameters
Runtime configuration
Environment variables
Service configuration
Zuul configuration
Hystrix configuration
AT-TLS
Getting started
Getting started
Using the Zowe Desktop
Using the Zowe Desktop
Navigating the Zowe Desktop
 Accessing the Zowe Desktop
Logging in and out of the Zowe Desktop
Changing user password
Updating an expired password
Pinning applications to the task bar
Open application in new tab
Personalizing the Desktop
Changing the desktop language
Zowe Desktop application plugins
Hello World Sample
IFrame Sample
Sample Angular App
Sample React App
3270 Terminal
VT Terminal
API Catalog
Editor
JES Explorer
IP Explorer
MVS Explorer
USS Explorer
Using the Editor
Using the Editor
Specifying a highlighting language
Open a dataset
Deleting a file or folder
Opening a directory
Creating a new directory
Creating a new file
Hotkeys
Using API Catalog
Using API Catalog
API Versioning
View Service Information and API Documentation in the API Catalog
Swagger "Try it out" functionality in the API Catalog
Make a request
Static APIs refresh functionality in the API Catalog
Change password via API Catalog
Using Metrics Service (Technical Preview)
Using Metrics Service (Technical Preview)
API Mediation Layer Metrics Service Demo Video
View HTTP Metrics in the Metrics Service Dashboard
Using Zowe CLI
Using Zowe CLI
Displaying help
Displaying help
Top-level help
Group, action, and object help
Launch local web help
Viewing web help
Understanding core command groups
Understanding core command groups
auth
config
daemon
plugins
profiles
provisioning
zos-console
zos-files
zos-jobs
zos-ssh
zos-workflows
zos-tso
zosmf
Issuing your first command
Issuing your first command
Using daemon mode
Using daemon mode
Preparing for installation
Enable daemon mode
Restart daemon mode
Disable daemon mode
Configure daemon mode on z/Linux operating systems
Configure daemon mode on z/Linux operating systems
Using profiles
Using profiles
Zowe CLI profile types
Tips for using Zowe CLI profiles
Important information about team profiles
Displaying profile help
Service profiles
Base profiles
Tips for using base profiles
Profile best practices
Testing connections to z/OSMF
Without a profile
Default profile
Specific profile
Using team profiles
Using team profiles
Initializing team configuration
Initializing team configuration
Create team profile configuration files
Connecting profiles to API Mediation Layer
Team configuration for application developers
Team configuration for application developers
Initializing user-specific configuration
Editing team profiles
Team configuration for team leaders
Team configuration for team leaders
Sharing team configuration files
Profile scenarios
Access to one or more LPARs that contain services that share the same credentials
Access to one or more LPARs contain services that do not share the same credentials
Access to LPARs that access services through one API Mediation Layer
Access to LPARs that access services through one API Mediation Layer using certificate
authentication
Sharing team configuration files
Sharing team configuration files
Network drive
Project repository and web server
Managing credential security
Managing credential security
 Changes to secure credential storage
Storing properties automatically
Storing properties automatically
Integrating with API Mediation Layer
Integrating with API Mediation Layer
How token management works
Logging in
Logging out
Accessing a service through API ML
Specifying a base path
Accessing multiple services with SSO
Accessing services through SSO + one service not through APIML
Accessing services through SSO + one service through API ML but not SSO
Working with certificates
Working with certificates
Configure certificates signed by a Certificate Authority (CA)
Extend trusted certificates on client
Bypass certificate requirement
Completing advanced tasks
Completing advanced tasks
Using environment variables
Formatting environment variables
Setting environment variables in an automation server
Using the prompt feature
Enable prompt
Always prompt
Change the keyword for prompt
Writing scripts
Sample script library
Example: Clean up Temporary Data Sets
Example: Submit Jobs and Save Spool Output
Extending Zowe CLI
Extending Zowe CLI
Software requirements for Zowe CLI plug-ins
Software requirements for Zowe CLI plug-ins
Installing Zowe CLI plug-ins
Installing Zowe CLI plug-ins
Installing plug-ins from an online registry
 Installing plug-ins from a local package
Validating plug-ins
Updating plug-ins
Update plug-ins from an online registry
Update plug-ins from a local package
Uninstall Plug-ins
IBM® CICS® Plug-in for Zowe CLI
IBM® CICS® Plug-in for Zowe CLI
Use cases
Commands
Software requirements
Installing
Creating a user profile
IBM® Db2® Database Plug-in for Zowe CLI
IBM® Db2® Database Plug-in for Zowe CLI
Use cases
Commands
Software requirements
Installing
Installing from an online registry
Installing from a local package
Addressing the license requirement
Server-side license
Client-side license
Creating a user profile
SQL0805N: Database BIND
M1 processor installation
M1 processor installation
IBM® z/OS FTP Plug-in for Zowe CLI
IBM® z/OS FTP Plug-in for Zowe CLI
Use cases
Commands
Software requirements
Installing
Creating a user profile
IBM® IMS™ Plug-in for Zowe CLI
IBM® IMS™ Plug-in for Zowe CLI
Use cases
 Commands
Software requirements
Installing
Creating user profiles
IBM® MQ Plug-in for Zowe CLI
IBM® MQ Plug-in for Zowe CLI
Use cases
Using IBM MQ plug-in commands
Software requirements
Installing
Creating a user profile
Visual Studio Code (VS Code) Extension for Zowe
Visual Studio Code (VS Code) Extension for Zowe
Software Requirements
Profile notes:
Installing
Configuration
Relevant Information
Zowe Explorer Profiles
Zowe Explorer Profiles
Configuring team profiles
Creating team configuration files
Managing profiles
Sample profile configuration
Working with Zowe Explorer profiles
Validating profiles
Using base profiles and tokens with existing profiles
Accessing services through API ML using SSO
Logging in to the Authentication Service
Configuring Zowe Application Framework
Configuring Zowe Application Framework
Accessing the App Server
Accessing the Desktop
Accessing ZSS
Configuration file
app-server configuration
zss configuration
Environment variables
 Configuring the framework as a Mediation Layer client
Setting up terminal app plugins
Setting up the TN3270 mainframe terminal app plugin
Setting up the VT Terminal app plugin
Network configuration
HTTPS
HTTP
Configuration Directories
Old defaults
App plugin configuration
Logging configuration
Enabling tracing
Log files
ZSS configuration
ZSS 64 or 31 bit modes
Using AT-TLS in the App Framework
Creating AT-TLS certificates and keyring using RACF
Defining the AT-TLS rule
Using multiple ZIS instances
Controlling access to apps
Enabling RBAC
Controlling app access for all users
Controlling app access for individual users
Controlling access to dataservices
Defining the RACF ZOWE class
Creating authorization profiles
Creating generic authorization profiles
Configuring basic authorization
Endpoint URL length limitations
Multi-factor authentication configuration
Session duration and expiration
Configuration
Administering the servers and plugins using an API
Configuring Zowe CLI environment variables
Configuring Zowe CLI environment variables
Setting the CLI home directory
Setting CLI log levels
Setting CLI daemon mode properties
Configuring the Zowe APIs
Configuring the Zowe APIs
Advanced Gateway features configuration
Advanced Gateway features configuration
SAF as an Authentication provider
Enable JWT token refresh endpoint
Change password with SAF provider
Change password with z/OSMF provider
Gateway retry policy
Gateway client certificate authentication
Gateway timeouts
CORS handling
Encoded slashes
Connection limits
Routed instance header
Distributed load balancer cache
Replace or remove the Catalog with another service
API Mediation Layer as a standalone component
SAF Resource Checking
Checking providers
Discovery Service configuration parameters
Discovery Service configuration parameters
Zowe runtime configuration parameters
API ML configuration
Eureka configuration
API Gateway configuration parameters
API Gateway configuration parameters
Runtime configuration
Environment variables
Service configuration
Zuul configuration
Hystrix configuration
AT-TLS
Extending Zowe
Extending Zowe
Extend Zowe CLI
Extend Zowe API Mediation Layer
Dynamic API registration
 Static API registration
Add a plug-in to the Zowe Desktop
Extend Zowe Explorer
Sample extensions
Sample Zowe API and API Catalog extension
Sample Zowe Desktop extension
Packaging z/OS extensions
Packaging z/OS extensions
Zowe server component package format
Zowe component manifest
Sample manifests
Install Zowe server component
Install Zowe server component
Install component
Enable and disable component
Install and configure manually
Zowe core components
Zowe z/OS extensions
Zowe server component runtime lifecycle
Zowe server component runtime lifecycle
Zowe runtime lifecycle
Zowe component runtime lifecycle
Validate
Configure
Start
Creating and adding Zowe extension containers
Creating and adding Zowe extension containers
1. Build and publish an extension image to a registry
2. Define Deployment or Job object
3. Start your component
Zowe Containerization Conformance Criteria
Zowe Containerization Conformance Criteria
Image
Base Image
Multi-CPU Architecture
Image Label
Tag
Files and Directories
 User zowe
Multi-Stage Build
Runtime
General rules
Persistent Volume(s)
Files and Directories
ConfigMap and Secrets
ompzowe/zowe-launch-scripts Image and initContainers
Command Override
Environment Variables
CI/CD
Build, Test and Release
Developing for Zowe CLI
Developing for Zowe CLI
How to contribute
Getting started
Tutorials
Plug-in development overview
Imperative CLI Framework documentation
Contribution guidelines
Setting up your development environment
Setting up your development environment
Prerequisites
Initial setup
Branches
Clone zowe-cli-sample-plugin and build from source
(Optional) Run the automated tests
Next steps
Installing the sample plug-in
Installing the sample plug-in
Overview
Installing the sample plug-in to Zowe CLI
Viewing the installed plug-in
Using the installed plug-in
Testing the installed plug-in
Next steps
Extending a plug-in
Extending a plug-in
 Overview
Creating a Typescript interface for the Typicode response data
Creating a programmatic API
Checkpoint one
Creating a command definition
Creating a command handler
Checkpoint two
Using the installed plug-in
Summary
Next steps
Developing a new plug-in
Developing a new plug-in
Overview
Cloning the sample plug-in source
Changing package.json
Adjusting Imperative CLI Framework configuration
Adding third-party packages
Creating a Node.js programmatic API
Exporting your API
Checkpoint
Defining commands
Trying your command
Bringing together new tools!
Next steps
Implementing profiles in a plug-in
Implementing profiles in a plug-in
Onboarding Overview
Onboarding Overview
Prerequisites
Service Onboarding Guides
Recommended guides for services using Java
Recommended guides for services using Node.js
Guides for Static Onboarding and Direct Call Onboarding
Documentation for legacy enablers
Verify successful onboarding to the API ML
Verifying service discovery through Discovery Service
Verifying service discovery through the API Catalog
Sample REST API Service
Onboarding a REST API service with the Plain Java Enabler (PJE)
Onboarding a REST API service with the Plain Java Enabler (PJE)
Introduction
Onboarding your REST service with API ML
Prerequisites
Configuring your project
Gradle build automation system
Maven build automation system
Configuring your service
REST service identification
Administrative endpoints
API info
API routing information
API Catalog information
Authentication parameters
API Security
SAF Keyring configuration
Eureka Discovery Service
Custom Metadata
Registering your service with API ML
Validating the discoverability of your API service by the Discovery Service
Troubleshooting
API Mediation Layer onboarding configuration
API Mediation Layer onboarding configuration
Introduction
Configuring a REST service for API ML onboarding
Plain Java Enabler service onboarding API
Automatic initialization of the onboarding configuration by a single method call
Validating successful onboarding with the API Mediation Layer
Loading YAML configuration files
Loading a single YAML configuration file
Loading and merging two YAML configuration files
Onboarding a service with the Zowe API Meditation Layer without an onboarding enabler
Onboarding a service with the Zowe API Meditation Layer without an onboarding enabler
Introduction
Registering with the Discovery Service
API Mediation Layer Service onboarding metadata
Sending a heartbeat to API Mediation Layer Discovery Service
 Validating successful onboarding with the API Mediation Layer
External Resources
Onboarding a Spring Boot based REST API Service
Onboarding a Spring Boot based REST API Service
Outline of onboarding a REST service using Spring Boot
Selecting a Spring Boot Enabler
Configuring your project
Gradle build automation system
Maven build automation system
Configuring your Spring Boot based service to onboard with API ML
Sample API ML Onboarding Configuration
Authentication properties
API ML Onboarding Configuration Sample
SAF Keyring configuration
Custom Metadata
Registering and unregistering your service with API ML
Unregistering your service with API ML
Basic routing
Adding API documentation
Validating the discoverability of your API service by the Discovery Service
Troubleshooting
Onboarding a Micronaut based REST API service
Onboarding a Micronaut based REST API service
Set up your build automation system
Configure the Micronaut application
Add API ML configuration
Add Micronaut configuration
(Optional) Set up logging configuration
Validate successful registration
Onboarding a Node.js based REST API service
Onboarding a Node.js based REST API service
Introduction
Onboarding your Node.js service with API ML
Prerequisites
Installing the npm dependency
Configuring your service
Registering your service with API ML
Validating the discoverability of your API service by the Discovery Service
Onboard a REST API without code changes required
Onboard a REST API without code changes required
Identify the APIs that you want to expose
Define your service and API in YAML format
Route your API
Customize configuration parameters
Add and validate the definition in the API Mediation Layer running on your machine
Add a definition in the API Mediation Layer in the Zowe runtime
(Optional) Check the log of the API Mediation Layer
(Optional) Reload the services definition after the update when the API Mediation Layer is already
started
Onboarding a REST API service with the YAML Wizard
Onboarding a REST API service with the YAML Wizard
Onboarding your REST service with the Wizard
Zowe API Mediation Layer Single-Sign-On Overview
Zowe API Mediation Layer Single-Sign-On Overview
Zowe API ML client
API service accessed via Zowe API ML
Existing services that cannot be modified
Further resources
Obtaining Information about API Services
Obtaining Information about API Services
API ID in the API Mediation Layer
Protection of Service Information
API Endpoints
Obtain Information about a Specific Service
Obtain Information about All Services
Obtain Information about All Services with a Specific API ID
Response Format
WebSocket support in API Gateway
WebSocket support in API Gateway
Security and Authentication
Subprotocols
High availability
Diagnostics
Limitations
Create an Extension for API ML
Create an Extension for API ML
 Call the REST endpoint for validation
API Mediation Layer Message Service Component
API Mediation Layer Message Service Component
Message Definition
Creating a message
Mapping a message
API ML Logger
Zowe API Mediation Layer Security
Zowe API Mediation Layer Security
How API ML transport security works
Transport layer security
Authentication
Zowe API ML services
Zowe API ML TLS requirements
Authentication for API ML services
Authentication parameters
Authentication providers
Authorization
JWT Token
z/OSMF JSON Web Tokens Support
API ML truststore and keystore
API ML SAF Keyring
Discovery Service authentication
Setting ciphers for API ML services
ZAAS Client
Pre-requisites
API Documentation
Getting Started (Step by Step Instructions)
Certificate management in Zowe API Mediation Layer
Running on localhost
Zowe runtime on z/OS
API Mediation Layer routing
API Mediation Layer routing
Terminology
APIML Basic Routing (using Service ID and version)
Implementation Details
Basic Routing (using only the service ID)
Enabling PassTicket creation for API Services that Accept PassTickets
Enabling PassTicket creation for API Services that Accept PassTickets
Overview
Outline for enabling PassTicket support
Security configuration that allows the Zowe API Gateway to generate PassTickets for an API service
ACF2
Top Secret
RACF
API services that support PassTickets
API Services that register dynamically with API ML that provide authentication information
API Services that register dynamically with API ML but do not provide metadata
API services that are defined using a static YAML definition
Adding YAML configuration to API services that register dynamically with API ML
Custom Metadata
Custom Metadata
API Versioning
API Versioning
Introduction
Versioning
REST
Data Model
Service and instance
API Versioning
Implement a new SAF IDT provider
Implement a new SAF IDT provider
How to create a SAF IDT provider
How to integrate your extension with API ML
How to use the SAF IDT provider
How to use an existing SAF IDT provider
Using the Caching Service
Using the Caching Service
Architecture
Storage methods
VSAM
Redis
Infinispan
InMemory
How to start the service
Methods to use the Caching service API
 Configuration properties
Authentication
Direct calls
Routed calls through API Gateway
Using VSAM as a storage solution through the Caching service
Using VSAM as a storage solution through the Caching service
Understanding VSAM
VSAM configuration
VSAM performance
Using Redis as a storage solution through the Caching service
Using Redis as a storage solution through the Caching service
Understanding Redis
Redis replica instances
Redis Sentinel
Redis SSL/TLS
Redis and Lettuce
Redis configuration
Overview
Overview
How Zowe Application Framework works
Tutorials
Samples
Sample Iframe App
Sample Angular App
Sample React App
User Browser Workshop Starter App
Plug-ins definition and structure
Plug-ins definition and structure
pluginDefinition.json
Application Plugin filesystem structure
Root files and directories
Dev and source content
Runtime content
Default user configuration
App-to-App Communication
Documentation
Location of Plugin files
pluginsDir directory
 Application Dataservices
Application Configuration Data
Building plugin apps
Building plugin apps
Building web content
Building app server content
Building zss server content
Tagging plugin files on z/OS
Building Javascript content (*.js files)
Installing
Packaging
Installing Plugins
Installing Plugins
By filesystem
Adding/Installing
Removing
Upgrading
Modifying without server restart (Exercise to the reader)
By REST API
Plugin management during development
Embedding plugins
Embedding plugins
How to interact with embedded plugin
How to destroy embedded plugin
How to style a container for the embedded plugin
Applications that use embedding
Dataservices
Dataservices
Defining dataservices
Schema
Defining Java dataservices
Prerequisites
Defining Java dataservices
Defining Java Application Server libraries
Java dataservice logging
Java dataservice limitations
Using dataservices with RBAC
Dataservice APIs
 Router-based dataservices
ZSS based dataservices
Documenting dataservices
Authentication API
Authentication API
Handlers
Handler installation
Handler configuration
Handler context
Handler capabilities
Examples
High availability (HA)
REST API
Check status
Authenticate
User not authenticated or not authorized
Not authenticated
Not authorized
Refresh status
Logout
Password changes
Internationalizing applications
Internationalizing applications
Internationalizing Angular applications
Internationalizing React applications
Internationalizing application desktop titles
Zowe Desktop and window management
Zowe Desktop and window management
Loading and presenting application plug-ins
Plug-in management
Application management
Windows and Viewports
Viewport Manager
Injection Manager
Plug-in definition
Logger
Launch Metadata
Viewport Events
 Window Events
Window Actions
Framework API examples
Configuration Dataservice
Configuration Dataservice
Resource Scope
REST API
REST query parameters
REST HTTP methods
Administrative access and group
Application API
Internal and bootstrapping
Packaging Defaults
Plug-in definition
Aggregation policies
Examples
URI Broker
URI Broker
Accessing the URI Broker
Natively:
In an iframe:
Functions
Accessing an application plug-in's dataservices
Accessing application plug-in's configuration resources
Accessing static content
Accessing the application plug-in's root
Server queries
Application-to-application communication
Application-to-application communication
Why use application-to-application communication?
Actions
Action target modes
Action types
Loading actions
App2App via URL
Dynamically
Saved on system
Recognizers
 Recognition clauses
Loading Recognizers at runtime
Recognizer example
Dispatcher
Registry
Pulling it all together in an example
Configuring IFrame communication
Configuring IFrame communication
Error reporting UI
Error reporting UI
ZluxPopupManagerService
ZluxErrorSeverity
ErrorReportStruct
Implementation
Declaration
Usage
HTML
Logging utility
Logging utility
Logging objects
Logger IDs
Accessing logger objects
Logger
Component logger
Logger API
Component Logger API
Log Levels
Logging verbosity
Configuring logging verbosity
Using log message IDs
Message ID logging examples
Using Conda to make and manage packages of Application Framework Plugins
Using Conda to make and manage packages of Application Framework Plugins
Initial Conda setup
Managing Conda channels
Searching for packages
Using Conda with Zowe
Setting environment variables temporarily:
 Setting environment variables persistently
Installing a Zowe plugin
Zowe plugin configuration
Zowe package structure
Building Conda packages for Zowe
Defining package properties
Creating build step
Lifecycle scripts
Adding configuration to Conda packages
Extending Zowe Explorer
Extending Zowe Explorer
Developing for Zowe SDKs
Developing for Zowe SDKs
Zowe Conformance Program
Zowe Conformance Program
Introduction
How to participate
How to suggest updates to the Zowe conformance program
Troubleshooting
Troubleshooting
Known problems and solutions
Collecting data for Zowe problems
Verifying a Zowe release's integrity
Understanding the Zowe release
Understanding the Zowe release
Understanding the Zowe release
Zowe releases
Patch
Minor release
Major release
Check the Zowe release number
Verify Zowe runtime directory
Verify Zowe runtime directory
Troubleshooting Kubernetes environments
Troubleshooting Kubernetes environments
ISSUE: Deployment and ReplicaSet failed to create pod
ISSUE: Failed to create services
Troubleshooting API ML
Troubleshooting API ML
Enable API ML Debug Mode
Change the Log Level of Individual Code Components
Known Issues
API ML stops accepting connections after z/OS TCP/IP stack is recycled
SEC0002 error when logging in to API Catalog
API ML throws I/O error on GET request and cannot connect to other services
Certificate error when using both an external certificate and Single Sign-On to deploy Zowe
Browser unable to connect due to a CIPHER error
API Components unable to handshake
Java z/OS components of Zowe unable to read certificates from keyring
Error Message Codes
Error Message Codes
API mediation utility messages
ZWEAM000I
API mediation common messages
ZWEAO102E
ZWEAO104W
ZWEAO105W
ZWEAO106W
ZWEAO401E
Common service core messages
ZWEAM100E
ZWEAM101E
ZWEAM102E
ZWEAM103E
ZWEAM104E
ZWEAM400E
ZWEAM500W
ZWEAM501W
ZWEAM502E
ZWEAM503E
ZWEAM504E
ZWEAM505E
ZWEAM506E
ZWEAM507E
ZWEAM508E
ZWEAM509E
 ZWEAM510E
ZWEAM511E
ZWEAM600W
ZWEAM700E
ZWEAM701E
Security common messages
ZWEAT100E
ZWEAT103E
ZWEAT403E
ZWEAT409E
ZWEAT410E
ZWEAT411E
ZWEAT412E
ZWEAT413E
ZWEAT414E
ZWEAT415E
ZWEAT416E
ZWEAT601E
ZWEAT602E
ZWEAT603E
ZWEAT604E
Security client messages
ZWEAS100E
ZWEAS101E
ZWEAS103E
ZWEAS104E
ZWEAS105E
ZWEAS120E
ZWEAS121E
ZWEAS123E
ZWEAS130E
ZWEAS131E
ZAAS client messages
ZWEAS100E
ZWEAS120E
ZWEAS121E
ZWEAS122E
ZWEAS170E
 ZWEAS400E
ZWEAS401E
ZWEAS404E
ZWEAS417E
ZWEAS130E
ZWEAS500E
ZWEAS501E
ZWEAS502E
ZWEAS503E
Discovery service messages
ZWEAD400E
ZWEAD401E
ZWEAD700W
ZWEAD701E
ZWEAD702W
ZWEAD703E
ZWEAD704E
Gateway service messages
ZWEAG500E
ZWEAG700E
ZWEAG701E
ZWEAG702E
ZWEAG704E
ZWEAG705E
ZWEAG706E
ZWEAG707E
ZWEAG708E
ZWEAG709E
ZWEAG710E
ZWEAG711E
ZWEAG712E
ZWEAG713E
ZWEAG714E
ZWEAG715E
ZWEAG716E
ZWEAG100E
ZWEAG101E
ZWEAG102E
 ZWEAG103E
ZWEAG104E
ZWEAG105E
ZWEAG106W
ZWEAG107W
ZWEAG108E
ZWEAG109E
ZWEAG110E
ZWEAG120E
ZWEAG121E
ZWEAS123E
ZWEAG130E
ZWEAG131E
ZWEAG140E
ZWEAG141E
ZWEAG150E
ZWEAG151E
API Catalog messages
ZWEAC100W
ZWEAC101E
ZWEAC102E
ZWEAC103E
ZWEAC104E
ZWEAC700E
ZWEAC701W
ZWEAC702E
ZWEAC703E
ZWEAC704E
ZWEAC705W
ZWEAC706E
ZWEAC707E
ZWEAC708E
ZWEAC709E
Raising a Zowe Application Framework issue on GitHub
Raising a Zowe Application Framework issue on GitHub
Raising a bug report
Raising an enhancement report
ZSS Error Message Codes
ZSS Error Message Codes
ZSS informational messages
ZWES0013I
ZWES0014I
ZWES0035I
ZWES0039I
ZWES0061I
ZWES0063I
ZWES0064I
ZWES1100I
ZWES1101I
ZWES1102I
ZWES1600I
ZWES1601I
ZSS error messages
ZWES1006E
ZWES1034E
ZWES1036E
ZWES1037E
ZWES1065E
ZSS warning messages
ZWES1000W
ZWES1005W
ZWES1012W
ZWES1060W
ZWES1103W
ZWES1201W
ZWES1103W
ZWES1602W
ZWES1603W
ZWES1604W
ZWES1605W
ZWES1606W
Troubleshooting Zowe CLI
Troubleshooting Zowe CLI
Problem
Environment
Before reaching out for support
 Resolving the problem
Gathering information to troubleshoot Zowe CLI
Gathering information to troubleshoot Zowe CLI
Identify the currently installed CLI version
Identify the currently installed versions of plug-ins
Environment variables
Log levels
CLI daemon mode
Home directory
Home directory structure
Location of logs
Profile configuration
Node.js and npm
npm configuration
npm log files
z/OSMF troubleshooting
z/OSMF troubleshooting
Alternative methods
Known Zowe CLI issues
Known Zowe CLI issues
EACCESS error when issing npm install command
Command not found message displays when issuing npm install commands
npm install -g Command Fails Due to an EPERM Error
Sudo syntax required to complete some installations
npm install -g command fails due to npm ERR! Cannot read property 'pause' of undefined error
Node.js commands do not respond as expected
Installation fails on Oracle Linux 6
Raising a CLI issue on GitHub
Raising a CLI issue on GitHub
Raising a bug report
Raising an enhancement report
Troubleshooting Zowe Explorer
Troubleshooting Zowe Explorer
Before reaching out for support
Known Zowe Explorer issues
Known Zowe Explorer issues
Data Set Creation Error
Opening Binary Files Error
Raising a Zowe Explorer issue on GitHub
Raising a Zowe Explorer issue on GitHub
Raising a bug report
Submitting a feature request
Troubleshooting Zowe Launcher
Troubleshooting Zowe Launcher
Enable Zowe Launcher Debug Mode
Error Message Codes
Error Message Codes
Zowe Launcher informational messages
ZWEL0001I
ZWEL0002I
ZWEL0003I
ZWEL0004I
ZWEL0005I
Zowe Launcher error messages
ZWEL0030E
ZWEL0038E
ZWEL0040E
Contribute to Zowe
Contribute to Zowe
Report bugs and enhancements
Fix issues
Send a Pull Request
Report security issues
Contribution guidelines
Promote Zowe
Helpful resources
Code categories
Code categories
Programming languages
Component-specific guidelines and tutorials
General code style guidelines
General code style guidelines
Whitespaces
Naming Conventions
Functions and methods
Variables
Pull requests guidelines
Pull requests guidelines
Documentation Guidelines
Documentation Guidelines
Contributing to external documentation
Component Categories
Server Core
Server Security
Microservices
Zowe Desktop Applications
Web Framework
CLI Plugins
Core CLI Imperative CLI Framework
Programming Languages
Typescript
Java
C
Introduction
Introduction
Clear
Consistent
Smart
Colors
Colors
Color palette
Light theme
Dark theme
Color contrast | WCAG AA standards
Typography
Typography
Typeface
Font weight
Body copy
Line scale
Line-height
Embed font
Import font
Specify in CSS
Grid
Grid
12 column grid
Gutters
Columns
Margins
Iconography
Iconography
Application icon
Application icon
General rules
Shape, size, and composition
Colors and shades
Verify the contrast
Use the Zowe palette
Layer Shadows
Use the long shadow for consistency.
Contributing to Zowe Documentation
Contributing to Zowe Documentation
Before You Get Started
Getting started checklist
The Zowe documentation repository
Sending a GitHub Pull Request
Opening an issue for Zowe documentation
Documentation style guide
Headings and titles
Technical elements
Tone
Word usage
Abbreviations
Structure and format
Word usage
Zowe CLI command reference guide
Zowe CLI command reference guide
Zowe API reference
Zowe API reference
zwe certificate keyring-jcl clean
zwe certificate keyring-jcl clean
 Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe certificate keyring-jcl connect
zwe certificate keyring-jcl connect
Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe certificate keyring-jcl generate
zwe certificate keyring-jcl generate
Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe certificate keyring-jcl import-ds
zwe certificate keyring-jcl import-ds
Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe certificate keyring-jcl
zwe certificate keyring-jcl
Sub-commands
Description
 Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe certificate pkcs12 create ca
zwe certificate pkcs12 create ca
Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe certificate pkcs12 create cert
zwe certificate pkcs12 create cert
Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe certificate pkcs12 create
zwe certificate pkcs12 create
Sub-commands
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe certificate pkcs12 export
zwe certificate pkcs12 export
Description
Inherited from parent command
Examples
 Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe certificate pkcs12 import
zwe certificate pkcs12 import
Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe certificate pkcs12 lock
zwe certificate pkcs12 lock
Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe certificate pkcs12 trust-service
zwe certificate pkcs12 trust-service
Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe certificate pkcs12
zwe certificate pkcs12
Sub-commands
Description
Inherited from parent command
Examples
Parameters
 Inherited from parent command
Errors
Inherited from parent command
zwe certificate verify-service
zwe certificate verify-service
Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe certificate
zwe certificate
Sub-commands
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe components install extract
zwe components install extract
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe components install process-hook
zwe components install process-hook
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe components install
zwe components install
Sub-commands
Description
Examples
Parameters only for this command
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe components disable
zwe components disable
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe components enable
zwe components enable
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe components
zwe components
Sub-commands
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe init apfauth
zwe init apfauth
Description
Examples
Parameters
 Inherited from parent command
Errors
Inherited from parent command
zwe init certificate
zwe init certificate
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe init mvs
zwe init mvs
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe init security
zwe init security
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe init stc
zwe init stc
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe init vsam
zwe init vsam
Description
 Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe init
zwe init
Sub-commands
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe internal config get
zwe internal config get
Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe internal config set
zwe internal config set
Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe internal config
zwe internal config
Sub-commands
Inherited from parent command
Examples
Parameters
 Inherited from parent command
Errors
Inherited from parent command
zwe internal container cleanup
zwe internal container cleanup
Description
Inherited from parent command
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe internal container init
zwe internal container init
Description
Inherited from parent command
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe internal container prestop
zwe internal container prestop
Description
Inherited from parent command
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe internal container
zwe internal container
Sub-commands
Description
Inherited from parent command
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe internal start component
zwe internal start component
 Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe internal start prepare
zwe internal start prepare
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe internal start
zwe internal start
Sub-commands
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe internal get-launch-components
zwe internal get-launch-components
Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe internal
zwe internal
Sub-commands
Description
Examples
Parameters
 Inherited from parent command
Errors
Inherited from parent command
zwe migrate for kubernetes
zwe migrate for kubernetes
Description
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe migrate for
zwe migrate for
Sub-commands
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe migrate
zwe migrate
Sub-commands
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe sample sub deep
zwe sample sub deep
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe sample sub second
zwe sample sub second
Description
Examples
Parameters
Inherited from parent command
 Errors
Inherited from parent command
zwe sample sub
zwe sample sub
Sub-commands
Description
Inherited from parent command
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe sample test
zwe sample test
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe sample
zwe sample
Sub-commands
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe support verify-fingerprints
zwe support verify-fingerprints
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe support
zwe support
Sub-commands
 Description
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe install
zwe install
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe start
zwe start
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe stop
zwe stop
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe version
zwe version
Description
Examples
Parameters
Inherited from parent command
Errors
Inherited from parent command
zwe
zwe
Sub-commands
Description
Examples
Parameters
Errors
Zowe YAML configuration file reference
Zowe YAML configuration file reference
High-level overview of YAML configuration file
Extract sharable configuration out of zowe.yaml
Configuration override
YAML configurations - certificate
YAML configurations - zowe
YAML configurations - java
YAML configurations - node
YAML configurations - zOSMF
YAML configurations - components
YAML configurations - haInstances
Auto-generated environment variables
Server component manifest file reference
Server component manifest file reference
Bill of Materials
Bill of Materials
Zowe overview
Version: v2.0.x LTS

Zowe™ is an open source software framework that allows mainframe development and operation teams to
securely manage, control, script, and develop on the mainframe. It was created to host technologies that
benefit the IBM Z platform for all members of the Z community, including Integrated Software Vendors
(ISVs), System Integrators, and z/OS consumers. Like Mac or Windows, Zowe comes with a set of APIs and
OS capabilities that applications build on and also includes some applications out of the box. Zowe offers
modern interfaces to interact with z/OS and allows you to work with z/OS in a way that is similar to what you
experience on cloud platforms today. You can use these interfaces as delivered or through plug-ins and
extensions that are created by clients or third-party vendors. Zowe is a project within the Open Mainframe
Project.

Zowe demo video

Watch this video to see a quick demo of Zowe.

Download the deck for this video | Download the script

Component overview
Zowe consists of the following components:
Zowe Application Framework
API Mediation Layer
Zowe CLI
Zowe Explorer
Zowe Client Software Development Kits SDKs
Zowe Launcher
Zowe Mobile - Incubator
ZEBRA (Zowe Embedded Browser for RMF/SMF and APIs) - Incubator
Zowe Application Framework
A web user interface (UI) that provides a virtual desktop containing a number of apps allowing access to
z/OS function. Base Zowe includes apps for traditional access such as a 3270 terminal and a VT Terminal, as
well as an editor and explorers for working with JES, MVS Data Sets and Unix System Services.
📖 Learn more
The Zowe Application Framework modernizes and simplifies working on the mainframe. With the Zowe
Application Framework, you can create applications to suit your specific needs. The Zowe Application
Framework contains a web UI that has the following features:
The web UI works with the underlying REST APIs for data, jobs, and subsystem, but presents the
information in a full screen mode as compared to the command line interface.
The web UI makes use of leading-edge web presentation technology and is also extensible through
web UI plug-ins to capture and present a wide variety of information.
The web UI facilitates common z/OS developer or system programmer tasks by providing an editor
for common text-based files like REXX or JCL along with general purpose data set actions for both
Unix System Services (USS) and Partitioned Data Sets (PDS) plus Job Entry System (JES) logs.
The Zowe Application Framework consists of the following components:
Zowe Desktop
The desktop, accessed through a browser. The desktop contains a number of applications,
including a TN3270 emulator for traditional Telnet or TLS terminal access to z/OS, a VT Termnial for
SSH commands, as well as rich web GUI applications including a JES Explorer for working with jobs
and spool output, a File Editor for working with USS directories and files and MVS data sets and
members. The Zowe desktop is extensible and allows vendors to provide their own applications to
run within the desktop. See Extending the Zowe Desktop. The following screen capture of a Zowe
desktop shows some of its composition as well as the TN3270 app, the JES Explorer, and the File
Editor open and in use.

Zowe Application Server

The Zowe Application Server runs the Zowe Application Framework. It consists of the Node.js
server plus the Express.js as a webservices framework, and the proxy applications that
communicate with the z/OS services and components.
ZSS Server
The ZSS Server provides secure REST services to support the Zowe Application Server. For
services that need to run as APF authorized code, Zowe uses an angel process that the ZSS Server
calls using cross memory communication. During installation and configuration of Zowe, you will
see the steps needed to configure and launch the cross memory server.
Application plug-ins
Several application-type plug-ins are provided. For more information, see Using the Zowe
Application Framework application plug-ins.
API Mediation Layer
Provides a gateway that acts as a reverse proxy for z/OS services, together with a catalog of REST APIs and
a dynamic discovery capability. Base Zowe provides core services for working with MVS Data Sets, JES, as
well as working with z/OSMF REST APIs. The API Mediation Layer also provides a framework for Single Sign
On (SSO).
📖 Learn more
The API Mediation Layer provides a single point of access for mainframe service REST APIs. The layer
offers enterprise, cloud-like features such as high-availability, scalability, dynamic API discovery,
consistent security, a single sign-on experience, and documentation. The API Mediation Layer facilitates
secure communication across loosely coupled microservices through the API Gateway. The API
Mediation Layer consists of three components: the Gateway, the Discovery Service, and the Catalog.
The Gateway provides secure communication across loosely coupled API services. The Discovery
Service enables you to determine the location and status of service instances running inside the API ML
ecosystem. The Catalog provides an easy-to-use interface to view all discovered services, their
associated APIs, and Swagger documentation in a user-friendly manner.
Key features
Consistent Access: API routing and standardization of API service URLs through the Gateway
component provides users with a consistent way to access mainframe APIs at a predefined
address.
Dynamic Discovery: The Discovery Service automatically determines the location and status of API
services.
High-Availability: API Mediation Layer is designed with high-availability of services and scalability in
mind.
Caching Service: This feature is designed for Zowe components in a high availability configuration.
It supports the High Availability of all components within Zowe, allowing components to be stateless
by providing a mechanism to offload their state to a location accessible by all instances of the
service, including those which just started.
Redundancy and Scalability: API service throughput is easily increased by starting multiple API
service instances without the need to change configuration.
Presentation of Services: The API Catalog component provides easy access to discovered API
services and their associated documentation in a user-friendly manner. Access to the contents of
the API Catalog is controlled through a z/OS security facility.
 Encrypted Communication: API ML facilitates secure and trusted communication across both
internal components and discovered API services.
API Mediation Layer architecture
The following diagram illustrates the single point of access through the Gateway, and the interactions
between API ML components and services:

Components
The API Layer consists of the following key components:
API Gateway
Services that comprise the API ML service ecosystem are located behind a gateway (reverse proxy). All
end users and API client applications interact through the Gateway. Each service is assigned a unique
service ID that is used in the access URL. Based on the service ID, the Gateway forwards incoming API
requests to the appropriate service. Multiple Gateway instances can be started to achieve high-
availability. The Gateway access URL remains unchanged. The Gateway is built using Netflix Zuul and
Spring Boot technologies.
Discovery Service
The Discovery Service is the central repository of active services in the API ML ecosystem. The
Discovery Service continuously collects and aggregates service information and serves as a repository
of active services. When a service is started, it sends its metadata, such as the original URL, assigned
serviceId, and status information to the Discovery Service. Back-end microservices register with this
service either directly or by using a Eureka client. Multiple enablers are available to help with service on-
boarding of various application architectures including plain Java applications and Java applications that
use the Spring Boot framework. The Discovery Service is built on Eureka and Spring Boot technology.
Discovery Service TLS/SSL
HTTPS protocol can be enabled during API ML configuration and is highly recommended. Beyond
encrypting communication, the HTTPS configuration for the Discovery Service enables heightened
security for service registration. Without HTTPS, services provide a username and password to register
in the API ML ecosystem. When using HTTPS, only trusted services that provide HTTPS certificates
signed by a trusted certificate authority can be registered.
API Catalog
The API Catalog is the catalog of published API services and their associated documentation. The
Catalog provides both the REST APIs and a web user interface (UI) to access them. The web UI follows
the industry standard Swagger UI component to visualize API documentation in OpenAPI JSON format
for each service. A service can be implemented by one or more service instances, which provide exactly
the same service for high-availability or scalability.
Catalog Security
 Access to the API Catalog can be protected with an Enterprise z/OS Security Manager such as IBM
RACF, ACF2, or Top Secret. Only users who provide proper mainframe credentials can access the
Catalog. Client authentication is implemented through the z/OSMF API.
Caching Service
It provides an API in high-availability mode which offers the possibility to store, retrieve and delete data
associated with keys. The service will be used only by internal Zowe applications and will not be
exposed to the internet.
Metrics Service (Technical Preview)
The Metrics Service provides a web user interface to visualize requests to API Mediation Layer services.
HTTP metrics such as number of requests and error rates are displayed for each API Mediation Layer
service. This service is currently in technical preview and is not ready for production.
Onboarding APIs
Essential to the API Mediation Layer ecosystem is the API services that expose their useful APIs. Use the
following topics to discover more about adding new APIs to the API Mediation Layer and using the API
Catalog:
Onboarding Overview
Onboard an existing Spring Boot REST API service using Zowe API Mediation Layer
Onboard an existing Node.js REST API service using Zowe API Mediation Layer
Using API Catalog

To learn more about the architecture of Zowe, see Zowe architecture.

Zowe CLI
Zowe CLI is a command-line interface that lets you interact with the mainframe in a familiar, off-platform
format. Zowe CLI helps to increase overall productivity, reduce the learning curve for developing mainframe
applications, and exploit the ease-of-use of off-platform tools. Zowe CLI lets you use common tools such as
Integrated Development Environments (IDEs), shell commands, bash scripts, and build tools for mainframe
development. Though its ecosystem of plug-ins, you can automate actions on systems such as IBM Db2,
IBM CICS, and more. It provides a set of utilities and services for users that want to become efficient in
supporting and building z/OS applications quickly.
📖 Learn more
Zowe CLI provides the following benefits:
Enables and encourages developers with limited z/OS expertise to build, modify, and debug z/OS
applications.
Fosters the development of new and innovative tools from a computer that can interact with z/OS.
Some Zowe extensions are powered by Zowe CLI, for example the Visual Studio Code Extension for
Zowe.
Ensure that business critical applications running on z/OS can be maintained and supported by
existing and generally available software development resources.
Provides a more streamlined way to build software that integrates with z/OS.
Note: For information about software requirements, installing, and upgrading Zowe CLI, see Installing
Zowe.
Zowe CLI capabilities
With Zowe CLI, you can interact with z/OS remotely in the following ways:
Interact with mainframe files: Create, edit, download, and upload mainframe files (data sets)
directly from Zowe CLI.
Submit jobs: Submit JCL from data sets or local storage, monitor the status, and view and
download the output automatically.
Issue TSO and z/OS console commands: Issue TSO and console commands to the mainframe
directly from Zowe CLI.
Integrate z/OS actions into scripts: Build local scripts that accomplish both mainframe and local
tasks.
Produce responses as JSON documents: Return data in JSON format on request for
consumption in other programming languages.
For detailed information about the available functionality in Zowe CLI, see Zowe CLI Command Groups.
For information about extending the functionality of Zowe CLI by installing plug-ins, see Extending Zowe
CLI.
More Information:
System requirements for Zowe CLI
Installing Zowe CLI
Zowe Explorer
Zowe Explorer is a Visual Studio Code extension that modernizes the way developers and system
administrators interact with z/OS mainframes. Zowe Explorer lets you interact with data sets, USS files, and
jobs that are stored on z/OS. The extension complements your Zowe CLI experience and lets you use
authentication services like API Mediation Layer. The extension provides the following benefits:
Enabling you to create, modify, rename, copy, and upload data sets directly to a z/OS mainframe.
Enabling you to create, modify, rename, and upload USS files directly to a z/OS mainframe.
Providing a more streamlined way to access data sets, uss files, and jobs.
Letting you create, edit, and delete Zowe CLI zosmf compatible profiles.
Letting you use the Secure Credential Store plug-in to store your credentials securely in the settings.
Letting you leverage the API Mediation Layer token-based authentication to access z/OSMF.
For more information, see Information roadmap for Zowe Explorer.
Zowe Client Software Development Kits (SDKs)
The Zowe Client SDKs consist of programmatic APIs that you can use to build client applications or scripts
that interact with z/OS. The following SDKs are available:
Zowe Node.js Client SDK
Zowe Python Client SDK
For more information, see Using the Zowe SDKs.
Zowe Launcher
Provides an advanced launcher for Zowe z/OS server components in a high availability configuration. It
performs the following operations:
Stopping the Zowe server components using the STOP (or P ) operator command
Stopping and starting specific server components without restarting the entire Zowe instance using
MODIFY (or F ) operator command

Zowe Mobile - Incubator

Lets you interact with your Zowe instance running on the mainframe from your mobile.
For more information, see Information roadmap for Zowe Mobile.
ZEBRA (Zowe Embedded Browser for RMF/SMF and APIs) - Incubator
Provides re-usable and industry compliant JSON formatted RMF/SMF data records, so that many other ISV
SW and users can exploit them using open-source SW for many ways.
For more information, see the ZEBRA documentation or visit the ZEBRA test/trial site.
Zowe Workflow wiZard - Incubator
The Workflow wiZard delivers a workflow builder which simplifies the creation of z/OSMF workflows. The
workflow builder reads a library of templates along with a set of properties, determines which steps are
necessary based upon rules that use property values, determines a suitable order to satisfy the workflow
engine requirements, inserts variable definitions when required, and outputs workflow XML.
For more information, see the Workflow Template Reference.

Zowe Third-Party Software Requirements and Bill of

Materials
Third-Party Software Requirements (TPSR)
Bill of Materials (BOM)
Zowe architecture
Version: v2.0.x LTS

Zowe™ is a collection of components that together form a framework that makes Z-based functionality
accessible across an organization. Zowe functionality includes exposing Z-based components, such as
z/OSMF, as REST APIs. The Zowe framework provides an environment where other components can be
included and exposed to a broader non-Z based audience.
The following diagram illustrates the high-level Zowe architecture.

The diagram shows the default port numbers that are used by Zowe. These are dependent on each instance
of Zowe and are held in the Zowe YAML configuration file.
Zowe components can be categorized by location: server or client. While the client is always an end-user
tool such as a PC, browser, or mobile device, the server components can be further categorized by what
machine they run on.
Zowe server components can be installed and run entirely on z/OS, but a subset of the components can
alternatively run on Linux or z/Linux via Docker. While on z/OS, many of these components run under UNIX
System Services (USS). The components that do not run under USS must remain on z/OS when using
Docker in order to provide connectivity to the mainframe.

Zowe architecture with high availability enablement on

Sysplex
The following diagram illustrates the difference in locations of Zowe components when deploying Zowe into
a Sysplex with high availability enabled as opposed to running all components on a single z/OS system.

Zowe has high availability feature build-in. To enable this feature, you can define haInstances section in
your YAML configuration file.
The diagram above shows that ZWESLSTC has started two Zowe instances running on two separate LPARs
that can be on the same or different sysplexes.
 The Sysplex distributor port sharing enables the API Gateway 7554 ports to be shared so that incoming
requests can be routed to either the gateway on LPAR A or LPAR B.
The discovery servers on each LPAR communicate with each other and share their registered instances,
which allows the API gateway on LPAR A to dispatch APIs to components either on its own LPAR, or
alternatively to components on LPAR B. As indicated on the diagram, each component has two input
lines: one from the API gateway on its own LPAR and one from the gateway on the other LPAR. When
one of the LPARs goes down, the other LPAR remains operating within the sysplex providing high
availability to clients that connect through the shared port irrespective of which Zowe instance is
serving the API requests.
The zowe.yaml file can be configured to start Zowe instances on more than two LPARS, and also to start
more than one Zowe instance on a single LPAR, thereby providing a grid cluster of Zowe components that
can meet availability and scalability requirements.
The configuration entries of each LPAR in the zowe.yaml file control which components are started. This
configuration mechanism makes it possible to start just the desktop and API Mediation Layer on the first
LPAR, and start all of the Zowe components on the second LPAR. Because the desktop on the first LPAR is
available to the gateway of the second LPAR, all desktop traffic is routed there.
The caching services for each Zowe instance, whether on the same LPAR, or distributed across the sysplex,
are connected to each other by the same shared VSAM data set. This arrangement allows state sharing so
that each instance behaves similarly to the user irrespective of where their request is routed.
For simplification of the diagram above, the Jobs and Files API servers are not shown as being started. If the
user defines Jobs and Files API servers to be started in the zowe.yaml configuration file, these servers
behave the same as the servers illustrated. In other words, these services register to their API discovery
server which then communicates with other discovery servers on other Zowe instances on either the same
or other LPARs. The API traffic received by any API gateway on any Zowe instance is routed to any of the
Jobs or Files API components that are available.
To learn more about Zowe with high availability enablement, see Configuring Sysplex for high availability.

Zowe architecture when running in Kubernetes cluster

The following diagram illustrates the difference in locations of Zowe components when deploying Zowe into
a Kubernetes cluster as opposed to running all components on a single z/OS system.
When deploying other server components into container orchestration software like Kubernetes, Zowe
follows standard Kubernetes practices. The cluster can be monitored and managed with common
Kubernetes administration methods.
All Zowe workloads run on a dedicated namespace ( zowe by default) to distinguish from other
workloads in same Kubernetes cluster.
Zowe has its own ServiceAccount to help with managing permissions.
Server components use similar zowe.yaml on z/OS, which are stored in ConfigMap and Secret ,
to configure and start.
Server components can be configured by using the same certificates used on z/OS components.
Zowe claims its own Persistent Volume to share files across components.
Each server component runs in separated containers.
Components may register themselves to Discovery with their own Pod name within the cluster.
Zowe workloads use the zowe-launch-scripts initContainers step to prepare required
runtime directories.
Only necessary components ports are exposed outside of Kubernetes with Service .

App Server
The App Server is a node.js server that is responsible for the Zowe Application Framework. This server
provides the Zowe desktop, which is accessible through a web browser via port 7556. The Zowe desktop
includes a number of applications that run inside the Application Framework such as a 3270 emulator and a
File Editor.

The App Server server logs write to <zowe.logDirectory>/appServer-yyyy-mm-dd-hh-mm.log .

The Application Framework provides REST APIs for its services that are included on the API catalog tile
Zowe Application Framework that can be viewed at
https://<ZOWE_HOST_IP>:7554/apicatalog/ui/v1/#/tile/ZLUX/zlux .

ZSS
The Zowe desktop delegates a number of its services to the ZSS server which it accesses through the http
port 7557. ZSS is written in C and has native calls to z/OS to provide its services. ZSS logs write to STDOUT
and STDERR for capture into job logs, but also as a file into <zowe.logDirectory>/zssServer-yyyy-
mm-dd-hh-mm.log .

API Gateway
The API Gateway is a proxy server that routes requests from clients on its northbound edge, such as web
browsers or the Zowe command line interface, to servers on its southbound edge that are able to provide
data to serve the request. The API Gateway is also responsible for generating the authentication token used
to provide single sign-on (SSO) functionality. The API Gateway homepage is
https://<ZOWE_HOST_IP>:7554 . Following authentication, this URL enables users to navigate to the
API Catalog.

API Catalog
The API Catalog provides a list of the API services that have registered themselves as catalog tiles. These
tiles make it possible to view the available APIs from Zowe's southbound servers, as well as test REST API
calls.

API Discovery
The API Discovery server acts as the registration service broker between the API Gateway and its
southbound servers. This server can be accessed through the URL https://<ZOWE_HOST_IP>:7552
making it possible to view a list of registered API services on the API discovery homepage.

Caching service
The Caching service aims to provide an API which offers the possibility to store, retrieve, and delete data
associated with keys. The service is used only by internal Zowe applications and is not exposed to the
internet. The Caching service URL is https://<ZOWE_HOST_IP>:7555 . For more information about the
Caching service, see the Caching service documentation.
Desktop Apps
Zowe provides a number of rich GUI web applications for working with z/OS. Such applications include the
Editor for files and datasets, the JES Explorer for jobs, and the IP Explorer for the TCPIP stack. You can
access them through the Zowe desktop.

File API and JES API

The File API server provides a set of REST APIs for working with z/OS data sets and Unix files. These APIs
can be abled in zowe server configuration.
The JES API server provides a set of REST APIs for working with JES. These APIs can be abled in zowe
server configuration.
Both the File API and JES API servers are registered as tiles on the API Catalog, so users can view the
Swagger definition and test API requests and responses.

Cross Memory server

The Cross Memory server is a low-level privileged server for managing mainframe data securely. For security
reasons, it is not an HTTP server. Instead, this server has a trust relationship with ZSS. Other Zowe
components can work through ZSS in order to handle z/OS data that would otherwise be unavailable or
insecure to access from higher-level languages and software.
Unlike all of the servers described above which run under the ZWESLSTC started task as address spaces
for USS processes, the Cross Memory server has its own separate started task ZWESISTC and its own user
ID ZWESIUSR that runs the program ZWESIS01 .
FAQ: Zowe and components
Version: v2.0.x LTS

Check out the following FAQs to learn more about the purpose and function of Zowe™.
Zowe FAQ
Zowe CLI FAQ
Zowe Explorer FAQ

Zowe FAQ
What is Zowe?
📖 Click to hide answer
Zowe is an open source project within the Open Mainframe Project that is part of The Linux Foundation.
The Zowe project provides modern software interfaces on IBM z/OS to address the needs of a variety of
modern users. These interfaces include a new web graphical user interface, a script-able command-line
interface, extensions to existing REST APIs, and new REST APIs on z/OS.

Who is the target audience for using Zowe?

📖 Click to hide answer
Zowe technology can be used by a variety of mainframe IT and non-IT professionals. The target
audience is primarily application developers and system programmers, but the Zowe Application
Framework is the basis for developing web browser interactions with z/OS that can be used by anyone.

What language is Zowe written in?

📖 Click to hide answer
Zowe consists of several components. The primary languages are Java and JavaScript. Zowe CLI and
Desktop are written in TypeScript. ZSS is written in C, while the cross memory server is written in metal
 C.

What is the licensing for Zowe?

📖 Click to hide answer
Zowe source code is licensed under EPL2.0. For license text click here and for additional information
click here.
In the simplest terms (taken from the FAQs above) - "...if you have modified EPL-2.0 licensed source
code and you distribute that code or binaries built from that code outside your company, you must make
the source code available under the EPL-2.0."

Why is Zowe licensed using EPL2.0?

📖 Click to hide answer
The Open Mainframe Project wants to encourage adoption and innovation, and also let the community
share new source code across the Zowe ecosystem. The open source code can be used by anyone,
provided that they adhere to the licensing terms.

What are some examples of how Zowe technology might be used by z/OS products
and applications?
📖 Click to hide answer
The Zowe Desktop (web user interface) can be used in many ways, such as to provide custom graphical
dashboards that monitor data for z/OS products and applications.
Zowe CLI can also be used in many ways, such as for simple job submission, data set manipulation, or
for writing complex scripts for use in mainframe-based DevOps pipelines.
The increased capabilities of RESTful APIs on z/OS allows APIs to be used in programmable ways to
interact with z/OS services.
What is the best way to get started with Zowe?
📖 Click to hide answer
Zowe provides a convenience build that includes the components released-to-date, as well as IP being
considered for contribution, in an easy to install package on Zowe.org. The convenience build can be
easily installed and the Zowe capabilities seen in action.
To install the complete Zowe solution, see Installing Zowe.
To get up and running with the Zowe CLI component quickly, see Zowe CLI quick start.

What are the prerequisites for Zowe?

📖 Click to hide answer
Prerequisites vary by component used, but in most cases the primary prerequisites are Java and
NodeJS on z/OS and the z/OS Management Facility enabled and configured. For a complete list of
software requirements listed by component, see System requirements for z/OS components and
System requirements for Zowe CLI.

What's the difference between using Zowe with or without Docker?

Technical Preview
📖 Click to hide answer
Docker is a download option for Zowe that allows you to run certain Zowe server components outside of
z/OS. The Docker image contains the Zowe components that do not have the requirement of having to
run on z/OS: The App server, API Mediation Layer, and the USS/MVS/JES Explorers.
Configurating components with Docker is similar to the procedures you would follow without Docker,
however tasks such as installation and running with Docker are a bit different, as these tasks become
Linux oriented, rather than utilizing Jobs and STCs.
NOTE: z/OS is still required when using the Docker image. Depending on which components of Zowe
you use, you'll still need to set up z/OS Management Facility as well as Zowe's ZSS and Cross memory
servers.
Is the Zowe CLI packaged within the Zowe Docker download?
Technical Preview
📖 Click to hide answer
At this time, the Docker image referred to in this documentation contains only Zowe server components.
It is possible to make a Docker image that contains the Zowe CLI, so additional Zowe content, such as
the CLI, may have Docker as a distribution option later.
If you are interested in improvements such as this one, please be sure to express that interest to the
Zowe community!

Does ZOWE support z/OS ZIIP processors?

📖 Click to hide answer
Only the parts of Zowe that involve Java code are ZIIP enabled. The API Mediation Layer composed of
the API Gateway, Discovery and Catalog servers along with any Java-based services that work with
them such as the Jobs and Datasets servers are ZIIP enabled. Also, the CLI and VSCode Explorer make
large use of z/OSMF, which is Java so they are ZIIP enabled as well. More details on portions of Zowe
which are Java (ZIIP) enabled can be found here.
This leaves C and NodeJS code which are not ZIIP enabled, BUT, we have a tech preview available
currently that allows execution of Java as well as NodeJS code, on Linux or zLinux via Docker. With the
tech preview, only the C code remains on z/OS, which is not ZIIP enabled.

How is access security managed on z/OS?

📖 Click to hide answer
Zowe components use typical z/OS System authorization facility (SAF) calls for security.

How is access to the Zowe open source managed?

 📖 Click to hide answer
The source code for Zowe is maintained on an Open Mainframe Project GitHub server. Everyone has
read access. "Committers" on the project have authority to alter the source code to make fixes or
enhancements. A list of Committers is documented in Committers to the Zowe project.

How do I get involved in the open source development?

📖 Click to hide answer
The best way to get started is to join a Zowe Slack channel and/or email distribution list and begin
learning about the current capabilities, then contribute to future development.
For more information about emailing lists, community calendar, meeting minutes, and more, see the
Zowe Community GitHub repo.
For information and tutorials about extending Zowe with a new plug-in or application, see Extending on
Zowe Docs.

When will Zowe be completed?

📖 Click to hide answer
Zowe will continue to evolve in the coming years based on new ideas and new contributions from a
growing community.

Can I try Zowe without a z/OS instance?

📖 Click to hide answer
IBM has contributed a free hands-on tutorial for Zowe. Visit the Zowe Tutorial page to learn about
adding new applications to the Zowe Desktop and and how to enable communication with other Zowe
components.
The Zowe community is also currently working to provide a vendor-neutral site for an open z/OS build
and sandbox environment.
 Zowe is also compatible with IBM z/OSMF Lite for non-production use. For more information, see
Configuring z/OSMF Lite on Zowe Docs.

Zowe CLI FAQ

Why might I use Zowe CLI versus a traditional ISPF interface to perform mainframe
tasks?
📖 Click to hide answer
For developers new to the mainframe, command-line interfaces might be more familiar than an ISPF
interface. Zowe CLI lets developers be productive from day-one by using familiar tools. Zowe CLI also
lets developers write scripts that automate a sequence of mainframe actions. The scripts can then be
executed from off-platform automation tools such as Jenkins automation server, or manually during
development.

With what tools is Zowe CLI compatible?

📖 Click to hide answer
Zowe CLI is very flexible; developers can integrate with modern tools that work best for them. It can
work in conjunction with popular build and testing tools such as Gulp, Gradle, Mocha, and Junit. Zowe
CLI runs on a variety of operating systems, including Windows, macOS, and Linux. Zowe CLI scripts can
be abstracted into automation tools such as Jenkins and TravisCI.

Where can I use the CLI?

📖 Click to hide answer
Usage Scenario Example
 Usage Scenario Example
Interactive use, in a
command prompt or bash Perform one-off tasks such as submitting a batch job.
terminal.
Interactive use, in an IDE Download a data set, make local changes in your editor, then upload
terminal the changed dataset back to the mainframe.
Scripting, to simplify Write a shell script that submits a job, waits for the job to complete,
repetitive tasks then returns the output.

Scripting, for use in Add a script to your Jenkins (or other automation tool) pipeline to
automated pipelines move artifacts from a mainframe development system to a test
system.

Which method should I use to install Zowe CLI?

📖 Click to hide answer
You can install Zowe CLI using the following methods:
Local package installation: The local package method lets you install Zowe CLI from a zipped file
that contains the core application and all plug-ins. When you use the local package method, you
can install Zowe CLI in an offline environment. We recommend that you download the package and
distribute it internally if your site does not have internet access.
Online NPM registry: The online NPM (Node Package Manager) registry method unpacks all of the
files that are necessary to install Zowe CLI using the command line. When you use the online
registry method, you need an internet connection to install Zowe CLI

How can I get Zowe CLI to run faster?

📖 Click to hide answer
 Zowe CLI runs significantly faster when you run it in daemon mode. Daemon mode significantly
improves the performance of Zowe CLI commands by running Zowe CLI as a persistent
background process. For more information, see Using daemon mode.

How can I manage profiles for my projects and teams?

📖 Click to hide answer
Zowe CLI V2 introduces team profiles. Using team profiles helps to improve the initial setup of
Zowe CLI by making service connection details easier to share and easier to store within projects.
For more information, see Using team profiles.

How can I get help with using Zowe CLI?

📖 Click to hide answer
You can get help for any command, action, or option in Zowe CLI by issuing the command 'zowe --
help'.
For information about the available commands in Zowe CLI, see Command Groups.
If you have questions, the Zowe Slack space is the place to ask our community!

How can I use Zowe CLI to automate mainframe actions?

📖 Click to hide answer
You can automate a sequence of Zowe CLI commands by writing bash scripts. You can then run
your scripts in an automation server such as Jenkins. For example, you might write a script that
moves your Cobol code to a mainframe test system before another script runs the automated tests.
Zowe CLI lets you manipulate data sets, submit jobs, provision test environments, and interact with
mainframe systems and source control management, all of which can help you develop robust
continuous integration/delivery.

How can I contribute to Zowe CLI?

 📖 Click to hide answer
As a developer, you can extend Zowe CLI in the following ways:
Build a plug-in for Zowe CLI
Contribute code to the core Zowe CLI
Fix bugs in Zowe CLI or plug-in code, submit enhancement requests via GitHub issues, and raise
your ideas with the community in Slack.
Note: For more information, see Developing for Zowe CLI.

Zowe Explorer FAQ

Why might I use Zowe Explorer versus a traditional ISPF interface to perform
mainframe tasks?
📖 Click to hide answer
The Zowe Explorer VSCode extension provides developers new to the mainframe with a modern UI,
allowing you to access and work with the data set, USS, and job functionalities in a fast and streamlined
manner. In addition, Zowe Explorer enables you to work with Zowe CLI profiles and issue TSO/MVS
commands.

How can I get started with Zowe Explorer?

📖 Click to hide answer
First of all, make sure you fulfill the following Zowe Explorer software requirements:
Get access to z/OSMF.
Install Node.js v8.0 or later.
Install VSCode.
Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST
interface. For more information, see z/OS Requirements.
 Once the software requirements are fulfilled, create a Zowe Explorer profile.
Follow these steps:
. Navigate to the explorer tree.
. Click the + button next to the DATA SETS, USS, or JOBS bar.
. Select the Create a New Connection to z/OS option.
. Follow the instructions, and enter all required information to complete the profile creation.
You can also watch Getting Started with Zowe Explorer to understand how to use the basic features of
the extension.

Where can I use Zowe Explorer?

📖 Click to hide answer
You can use Zowe Explorer either in VSCode or in Theia. For more information about Zowe Explorer in
Theia, see the Theia Readme.

How do I get help with using Zowe Explorer?

📖 Click to hide answer
Use the Zowe Explorer channel in Slack to ask the Zowe Explorer community for help.
Open a question or issue directly in the Zowe Explorer GitHub repository.

How can I use Secure Credential Storage for Zowe Explorer?

📖 Click to hide answer
The Secure Credential Store Plug-in is no longer required for Zowe Explorer.
Secure credential storage functionality is now contained in the Zowe CLI core application.
What types of profiles can I create for Zowe Explorer?
📖 Click to hide answer
Zowe Explorer V2 supports using Service Profiles, Base Profiles, and Team Profiles. For more
information, see Using profiles in the Using Zowe CLI section.

How can I use FTP as my back-end service for Zowe Explorer?

📖 Click to hide answer
See the Zowe FTP extension README in GitHub for information about how to build, install, and use FTP
as your back-end service for working with UNIX files.

How can I contribute to Zowe Explorer?

📖 Click to hide answer
As a developer, you may contribute to Zowe Explorer in the following ways:
Build a Zowe Explorer extension.
Contribute code to core Zowe Explorer.
Fix bugs in Zowe Explorer, submit enhancement requests via GitHub issues, and raise your ideas
with the community in Slack.
Note: For more information, see Extending Zowe Explorer.
FAQ: Zowe V2
Version: v2.0.x LTS

Where can I find the V1 and V2 LTS conformance criteria?

The Zowe Squads have prepared XLS spreadsheets with conformance criteria for all Zowe extensions
including: CLI, APIs, App Framework, and Explorer for VS Code. The spreadsheets clearly show the prior / V1
criteria alongside the new / V2 criteria. Please be aware, there are additions, deletions, and CHANGES to the
criteria. In some cases the change is simply that a BEST PRACTICE has been deemed REQUIRED. Use the
included fill color key to identify new changes for V2, reworded changes, or changes from V1 removed in V2.
See the Changes to the Conformance Criteria section at Zowe.org/vNext.

Whats the difference between "server.json" and "example-

zowe.yaml"?
The previous Zowe V1.x config, "server.json", has been removed from V2 and has been replaced with a new
yaml configuration file. The app server will no longer support instances/workspaces which only contain a
"server.json" config file and will fallback to a default configuration. In addition to the app server, ZSS will no
longer support "server.json".
The yaml Zowe configuration file contains configurations for the setup, install, and initialization of Zowe as
well as for individual components. This file allows users to customize dataset names, security related
configs, certificate setup/config, job name & job prefix, various runtime configs, high availability config, as
well as individual component configurations.
For more information on Zowe setup and the yaml configuration, run the following command in the
command line:
zwe init --help

What are the new default ports?

Four of the default Zowe ports have changed: the app server, zss, the jobs API, and the files API. The new
default app server port is 7556 (previously 8544) and the new zss port is 7557 (previously 8542). The new
jobs API port is 7558 (previously 8545) and the new files API is 7559 (previously 8547). The JES/USS/MVS
Explorer UI servers have been removed and thus no longer require port configurations.

How do I access Zowe through the API Mediation Layer in

V2?
In pervious V1.X versions of Zowe, the desktop could be accessed via the API Medation Layer by navigating
to https://${zowe.externalDomains[0]}:{zowe.externalPort}//ui/v1/zlux . In Zowe V2, the
route to access the desktop has changed to https://${zowe.externalDomains[0]}:
{zowe.externalPort}/zlux/ui/v1 . Such routing structure is applicable to other clients connected to
the API Gateway. For example, the API Catalog may be accessed via
https://${zowe.externalDomains[0]}:{zowe.externalPort}/apicatalog/ui/v1 .

What new frameworks are supported in V2?

The Zowe app framework now supports the more modern Angular 12, Corejs 3 and Typescript 4.

Why aren't the explorers appearing on my desktop

anymore?
By default, the explorers will not longer appear on the desktop if the instance is not configured to use the API
Mediation Layer.
Version 2.0.0 (April 2022)
Version: v2.0.x LTS

Welcome to the Version 2.0.0 release of Zowe!

Version 2.0 introduced breaking changes and a number of new features.
If you are upgrading from V1 to V2, review the Breaking changes first.
See New features and enhancements for a full list of changes to the functionality.
See Bug fixes for a list of V1 issues addressed in this release.
See Conformance and release compatibility for V2 Conformance Criteria updates and compatibility with
v1.
Download v2.0.0 build: Want to try new features as soon as possible? You can download the V2.0.0 build
from Zowe.org.
v2 office hours videos: Zowe held a series of v2 LTS office hours for extenders and consumers to introduce
all the V2 changes. Watch the videos to learn more about the new features.

Breaking changes
Zowe installation
You must pass -ppx when you unpax the Zowe convenience build to preserve extended file
attributes.
All utility scripts, like zowe-install.sh , zowe-install-xmem.sh , zowe-install-proc.sh ,
validate-directory-is-accessible.sh , are removed and migrated to the new zwe server
command format.
If you rely on some of the scripts, find the alternative new zwe command or shell library functions.
ZWESVSTC is removed and ZWESLSTC will replace it to start Zowe.

instance.env is deprecated and replaced by zowe.yml .

In V2, you use the P command to terminate Zowe instead of the C cancel command.
Zowe now allows fine-grained customization of log, workspace, and configuration directories. By
default, these directories remain grouped under an instance directory (same as Zowe v1).
 Environment variables are reorganized to better describe itself. All zowe.yaml configuration entries
will be automatically converted to environment variables for easy consumption. Check with the
community what the new alternative variable names are.
During Zowe configuration, redundant ip fields will be removed or consolidated in favor of
hostname or domains .

Component or extension manifest is mandatory. You must use the zwe components install
command to install the extension.
API Mediation Layer
Removed the support for the old path pattern (#1770). This includes the changes to the endpoints used
in ZAAS client. If your application uses ZAAS client, please verify whether the configuration properties
use the new path pattern ( /gateway/api/v1 instead of /api/v1/gateway ).
Removed the support for different authentication schemas for different instances of service (#1051).
Zowe Application Framework
Some configuration, such as port and IP values, are different by default in V2 but can be reconfigured to old
values. However, some application framework extensions may not work in V2 without enhancements.
zLUX App Manager
Due to new library versions, native apps such as Angular and React apps written for Zowe v1 may not
work in Zowe v2. Rebuilding the apps with the same versions and the latest webpack build scripts is
recommended.
zLUX Server Framework
The list of properties sent back from the /server/environment has changed to reflect the different
environment values present in Zowe v2
Adjusted the server to respect ZSS's new cookie format in which the port or HA instance ID is a
suffix of the ZSS cookie. This means that the server may not work properly when paired with a v1
ZSS and works best with v2 ZSS.
zLUX Editor
The app now uses angular 12, making it compatible with Zowe v2 desktop and incompatible with v1
desktop.
 Basic VT Terminal Emulator
Upgrade to Angular 12, Typescript 4, and Corejs 3 to match Desktop libraries in Zowe v2. This app may
no longer work in the Zowe v1 Desktop, and v2 should be used instead.
Basic TN3270 Display Emulator
Upgrade to Angular 12, Typescript 4, and Corejs 3 to match Desktop libraries in Zowe v2. This app may
no longer work in the Zowe v1 Desktop, and v2 should be used instead.
Sample angular app
The app now uses angular 12, making it compatible with Zowe v2 desktop and incompatible with v1
desktop.
Zowe CLI
Breaking changes for Zowe CLI end users:
zowe config no longer manages app settings (Imperative and CLI)

fail-on-error default changed to true for zowe plugins validate (Imperative and CLI)

Default Imperative and CLI log level changed from DEBUG to WARN (Imperative and CLI), which
potentially changes troubleshooting steps for providing information to support.
Breaking changes that could prevent a V1 plug-in or SDK from working in V2
CLI package should be removed as a plug-in peer dep (Imperative)
AbstractRestClient.mDecode defaults to true so any plug-in with custom RestClient
implementation that adds gzip decompression may break
The return value for PluginManagementFacility.requirePluginModuleCallback
changed. Application and plug-in developers requiring a module from a plug-in's relative path
using the requirePluginModuleCallback function no longer need to provide the plug-in
name in a separate variable this.pluginNmForUseInCallback = pluginName before
binding the class this.requirePluginModuleCallback.bind(this) . Instead they can call
this.requirePluginModuleCallback(pluginName) .
Previously in V1:
In V2:
 Breaking changes for Zowe CLI and Imperative plug-in developers
These changes only impact early adopters of @next as these are breaking changes made during the
technical preview validation phase. Thanks to the community for the feedback.
tokenType and tokenValue were combined into authToken , which later was reverted
(Imperative and CLI)
Options in zowe config group are renamed: --user is renamed to --user-config , and -
-global to --global-config .

Zowe.schema.json format changed a few times (version 2, version 3):

ConfigSchemas.loadProfileSchemas is changed to ConfigSchemas.loadSchema

Config.set no longer coerces string values to other types unless parseString = true
which might impact the SDK instead of CLI plug-ins.

New features and enhancements

Zowe installation
Introduced a new server command zwe to balance between simplification and flexibility on installation
and configuration.
Almost all Zowe utility scripts in V1 are consolidated into new zwe server command. This new
command defines consistent help messages, logging options, and so on. See the ZWE Command
Reference for more information.
Provides shell function library to help extensions to achieve common tasks. For example, execute
TSO command, operator command, submit job and check job completion, and so on.
Keep away from commands/functions marked as experimental and internal.
Installation / Configuration changes
During installation, no new runtime directory will be created.
A zowe.yaml file can be used to centralize all configuration options. This configuration is
compatible with all Zowe use cases (including high availability and containerization).
For almost all Zowe configuration steps, an automation option zwe init command is provided.
You can still choose to run all steps one by one.
Provides the --security-dry-run mode that allows you to generate security commands and
pass along to your system admin.
You can run all steps from USS now.
 A Zowe component or extension can use manifest.yaml to define how it interacts with Zowe and
other components.
The component or extension must define a manifest.yaml or manifest.json file to
describe itself. The manifest allows you to define how to register on Zowe API ML Discovery, how to
register under Zowe Desktop, and whether itʼs Java extension library for API ML, and so on.
Components can define their own configs in manifest.yaml which shows you how to
customize this component and provides default values if they are not defined. This option is
compatible with Zowe running in high availability mode.
Introduced new data sets to better organize the contents.
Added SZWEEXEC to contain few utility tools.
You can customize your own PARMLIB, APF Authorized LOADLIB and APF-authorized ZIS plug-ins
library. CUST.JCLIB is a data set where Zowe will store temporary JCLs.
Zowe API Mediation Layer
There is now the option to change your password via the Catalog UI (#2035) (139a231), closes #2035
Discovery service can be configured to modify the service ID at registration time (#2229) (63f6fde),
closes #2229
There is now the option to specify base packages for the extensions loader(#2081) (9a4be5a), closes
#2081
There is a new design of the logout panel in the Catalog dashboard (#2102) (1382f24), closes #2102
Add missing tooltips to all onboarding options (#2194) (5446fd5), closes #2194
Migrate API Catalog to the Material UI library (2c595d5, 0da7f15, 95da488, c60371d, 537fa34,
81ab2ed), closes #1169
Made various improvements to the onboarding wizard (#1772) (20dd70b), closes #1772
Zowe Application Framework
zLUX App Manager
New desktop library versions are Angular 6->12, Corejs 2->3, Typescript 2->4, and so on. For more
information, visit https://www.zowe.org/vnext.
The web-browser and admin-desktop-notification apps now contains a manifest file so that it can
be installed with zwe components install.
zLUX App Server
 Renamed ZLUX_ environment variables to ZWED_ for consistency. Backwards compatible with
old environment variables.
Added support for new logDirectory variable specification in zowe.yaml
Added support for reading from zowe.yaml instead of server.json
zLUX Server Framework
Added support for reading zowe.yaml directly, as opposed to server.json .
The server can now support checks on the existence and version of APIML if a plug-in states a
dependency on APIML in the "requirements.components" section of its plug-in definition.
The list of parameters for server configuration is now documented in json-schema for validation,
you can find this in the zlux repository
ZSS Package
New configuration option that allows to run 64-bit ZSS
zLUX Editor
Cookie name now has a suffix which includes the port or if in an HA instance, the HA ID.
Basic VT Terminal Emulator
The app now contains a manifest file so that it can be installed with zwe components install
Sample angular app
The app now contains a manifest file so that it can be installed with zwe components install
USS Explorer
USS-explorer no longer uses explorer-ui-server, but now depends on app-server. In a standard Zowe
environment, this will result in less processes but does break links about getting to the explorer via
APIML routes. The explorer is now available via the app-server's APIML route.
JES Explorer
JES-explorer no longer uses explorer-ui-server, but now depends on app-server. In a standard Zowe
environment, this will result in less processes but does break links about getting to the explorer via
APIML routes. The explorer is now available via the app-server's APIML route.
 MVS Explorer
MVS-explorer no longer uses explorer-ui-server, but now depends on app-server. In a standard Zowe
environment, this will result in less processes but does break links about getting to the explorer via
APIML routes. The explorer is now available via the app-server's APIML route.
Zowe CLI
Zowe CLI contains the following enhancements and changes:
Team Configuration:
Team configuration significantly improves the configuration/onboarding experience and provides the
ability to easily share configuration information with others in an organization.
Automatic Team Configuration:
Automatic team configuration leverages the Zowe API Mediation Layer to automatically configure
connections for conformant API ML services that also have a CLI plug-in.
Daemon Mode:
Daemon Mode significantly improves the performance of Zowe CLI by not requiring separate node
processes to be spawned for every command.
Secure by Default:
Secure by default provides a secure out-of-the-box experience by including the secure credential store
feature, previously offered as a plug-in in V1, as part of the core Zowe CLI package.
Migrating to Zowe V2 Team Configuration:
After installing @zowe/cli@zowe-v2-lts and all desired plug-ins @zowe-v2-lts , you can easily
migrate to Zowe V2 team configuration by issuing the following command:
Note: For more information, see Using Profiles.
Zowe CLI Plug-ins
Zowe maintained CLI plug-ins are Zowe V2 LTS conformant. As such, they integrate with Team
configuration, daemon mode, and the team configuration migration utility. For information about
enhancements and bug fixes, see the changelogs for the following plug-ins:
IBM CICS Plug-in for Zowe CLI
IBM Db2 Database Plug-in for Zowe CLI
IBM z/OS FTP Plug-in for Zowe CLI
IBM IMS Plug-in for Zowe CLI
IBM MQ Plug-in for Zowe CLI
Imperative CLI Framework
Imperative is the infrastructure on which various Zowe technologies are built. For information about
enhancements and bug fixes, see the Imperative CLI Framework changelog.
Nodejs SDK
The Nodejs SDK packages were updated to make use of key Zowe V2 features, including Team
Configuration. For information about enhancements and bug fixes, see the changelogs for the following
packages:
Core Package
Provisioning Package
z/OS Console Package
z/OS Files Package
z/OS Jobs Package
z/OS Logs Package
z/OS Management Facility Package
z/OS TSO Package
z/OS USS Package
z/OS Workflows Package
Zowe Explorer
Zowe Explorer makes use of Team Configuration and is secure by default. For information about
enhancements and bug fixes, see the following changelogs:
Zowe Explorer
Zowe Explorer CICS Extension
 Zowe Explorer FTP Extension

Bug fixes
Zowe API Mediation Layer
Caching service logging (#2222) (5ff64d9), closes #2222
Add x509 Authentication information to the API Documentation of the API Gateway (#2142) (072ad23),
closes #2142
Authorization provider set empty as default (#2107) (aa77926), closes #2107
Update URL of the API Catalog to work with the V2 version of the Zowe Desktop (6f4257a), closes
#2022
Zowe Application Framework
zLUX Server Framework
When paired with the Zowe server infrastructure, the app-server will now automatically register and de-
register plug-ins at startup depending on each plug-in's component enabled status.
ZSS Package
Do not use "tee" when log destination is /dev/null
Cookie name now has a suffix which includes the port or if in an HA instance, the HA ID.

Conformance and release compatibility

Backward compatibility
Zowe v1 conformant extensions/plug-ins are not guaranteed to be compatible with Zowe v2 and therefore
may not be operable. In general, plug-ins/extensions which leverage v2 APIs that have known breaking
changes are at high risk of incompatibility and unpredictable results.
Recommendation: All v1 extenders test with Zowe v2, identify any issues, and disclose results to
consumers to clearly indicate backward compatibility status in the extension documentation. If unable to
test, clearly document as such.
Forward compatibility
Zowe v2 conformant (planning to earn conformance) extensions/plug-ins are not guaranteed to be
compatible with Zowe v1 LTS. In general, plug-ins/extensions with no known dependency on any newly
introduced Zowe v2 functions are at minimum risk.
Recommendation: All v2 extenders test with Zowe v1 LTS, identify any issues, and disclose results to
consumers to clearly indicate forward compatibility status in the extension documentation. If unable to test,
clearly document as such.
Conformance compatibility
Zowe v1 conformant extensions/plug-ins are likely to require changes to meet Zowe v2 conformance criteria.
All extensions (regardless of v1 conformance status) must apply for v2 conformance and satisfy all required
v2 testing criteria. You can find the V2 Conformance Criteria here.
Recommendation: All extenders interested in earning v2 conformance review the v2 conformance criteria,
determine if technical changes are necessary, make appropriate modifications and prepare to apply for v2
conformance.
Need help? For assistance with reviewing or completing the Zowe Conformance Zowe v2 application, reach
out to members of the Zowe Onboarding Squad on Slack at https://slack.openmainframeproject.org in the
#zowe-onboarding channel.
Zowe V2 office hours videos
Version: v2.0.x LTS

Watch the series of Zowe office hours videos to learn more about the new features and enhancements in
Zowe Version 2 release.

Office hours for Zowe extenders

The following videos walk you through Zowe V2 updates from an extender's perspective. You can start with
general information and dive deeper in other sections for more details.
General information

General information Updates for extenders Wrap-up session

Zowe component updates

Zowe CLI Zowe API Mediation Layer Zowe Application Zo

Framework
Installation and V2 conformance

SSO and APIML SSO Conformance Systems and instal

Office hours for Zowe consumers

The following office hours walk you through Zowe V2 updates from a consumer's perspective. Listen to the
recordings to learn more about the enhancements that are introduced to each core component. The videos
will be ready later.
V2 Office Hours: Zowe API Mediation Layer for Consumers
V2 Office Hours: Zowe CLI for Consumers
V2 Office Hours: Zowe Explorers for Consumers
Zowe CLI quick start
Version: v2.0.x LTS

Get started with Zowe™ CLI quickly and easily.

This article presumes that your role is that of a systems administrator or you possess prerequisite
knowledge of command-line tools and writing scripts. If you prefer more detailed instructions, see Installing
Zowe CLI.

Installing
The following topics describe the Zowe CLI system requirements and the various methods to use to install
Zowe CLI.
Software Requirements
Before you install Zowe CLI, download and install Node.js and npm. Use an LTS version of Node.js that is
compatible with your version of npm. For a list of compatible versions, see Node.js Previous Releases.
(Linux only): On graphical Linux, install gnome-keyring and libsecret on your computer before you
install the Secure Credential Store. On headless Linux, follow the procedure documented in the SCS plug-in
Readme.
Installing Zowe CLI core from public npm
Issue the following command to install the core CLI.
Installing CLI plug-ins
The command installs most open-source plug-ins, but the IBM Db2 plug-in requires additional configuration
to install.
For more information, see Installing plug-ins.

Issuing your first commands

Issue zowe --help to display full command help. Append --help (alias -h ) to any command to see
available command actions and options.
Optionally, you can view the Zowe CLI web help in a browser window. For more information, see Displaying
help.
All Zowe CLI commands start with zowe followed by the name of the core command group. For example,
zowe plugins -h . To interact with the mainframe, type zowe followed by a command group, action,
and object. Use options to specify your connection details such as password and system name.
Listing all data sets under a high-level qualifier (HLQ)
Example:
Downloading a partitioned data-set (PDS) member to local file
Example:
See Understanding core command groups for a list of available functionality.

Team profiles
Zowe CLI V2-LTS now supports team profiles. The process of setting up team profiles is simple and can be
rolled out easily accross your organization. We highly recommend that you configure team profiles to
support your Zowe CLI implementation. For more information, see Using team profiles.

Using profiles
Zowe profiles let you store configuration details such as username, password, host, and port for a
mainframe system. Switch between profiles to quickly target different subsystems and avoid typing
connection details on every command.
Profile types
Most command groups require a zosmf-profile , but some plug-ins add their own profile types. For
example, the CICS plug-in has a cics-profile . The profile type that a command requires is defined in
the PROFILE OPTIONS section of the help response.
Tip: The first zosmf profile that you create becomes your default profile. If you don't specify any options
on a command, the default profile is used. Issue zowe profiles -h to learn about listing profiles and
setting defaults.
Creating zosmf profiles
Notes:
The port defaults to 443 if you omit the --port option. Specify a different port if your host system
does not use port 443.
If z/OSMF is configured for high availability in Sysplex, create the CLI zosmf-profile with DVIPA
address/hostname to ensure availability of REST services. For more information, see Configuring
z/OSMF high availability in Sysplex.
Using zosmf profiles
For detailed information about issuing commands, using profiles, and more, see Using CLI.

Writing scripts
You can write Zowe CLI scripts to streamline your daily development processes or conduct mainframe
actions from an off-platform automation tool such as Jenkins or TravisCI.
Example:
You want to delete a list of temporary datasets. Use Zowe CLI to download the list, loop through the list, and
delete each data set using the zowe zos-files delete command.
For more information, see Writing scripts.

Next steps
You successfully installed Zowe CLI, issued your first commands, and wrote a simple script! Next, you might
want to perform the following tasks:
Issue the zowe --help command to explore the product functionality, or review the online web help.
Learn how to configure Zowe CLI run Zowe CLI in daemon mode. Daemon mode significantly improves
the performance of Zowe CLI commands by running Zowe CLI as a persistent background process.
Learn about configuring environment variables to store configuration options.
Learn about integrating with API Mediation Layer.
Learn about how to write scripts and integrate them with automation server, such as Jenkins.
See what plug-ins are available for the CLI.
Learn about developing for the CLI (contributing to core and developing plug-ins).
Migrating Zowe server component from V1 to
Version: v2.0.x LTS

V2
This doc guides you through migrating an existing Zowe server component from version 1 to version 2.
To make Zowe server component compatible with Zowe version 2, you must update the following
configurations.
Component manifest
Lifecycle scripts
Environment variables
Packaging one component deliverable for both Zowe v1 and v2

Component manifest
In Zowe v2, the component must define a manifest file and package it into the extension's root directory.
This manifest file is used by Zowe to understand how this component should be installed, configured, and
started. For detailed information of this file, see Server Component Manifest File Reference.

Lifecycle scripts
In Zowe v2, lifecycle scripts can be located anywhere in your component directory. However, you must
explicitly define them in the commands section of the component manifest file.

Environment variables
Zowe v1 and v2 environment variables are not exact match. There are the following differences:
Some variables in Zowe v1 are removed in v2.
Some are separated into two or more variables.
Zowe v2 defines more configuration options than v1.
Review the following table for a detailed mapping of Zowe v1 and v2 variables.
 Zowe v1 Variable Zowe v2 YAML Confi
APIML_ALLOW_ENCODED_SLASHES components.gateway.apiml.service.al

APIML_CORS_ENABLED components.gateway.apiml.service.co

APIML_DEBUG_MODE_ENABLED components.gateway.debug , etc

APIML_ENABLE_SSO Removed in v2
APIML_GATEWAY_EXTERNAL_MAPPER components.gateway.apiml.security.x

APIML_GATEWAY_INTERNAL_HOST Not configurable in v2

APIML_GATEWAY_INTERNAL_PORT components.gateway.server.internal.

APIML_GATEWAY_TIMEOUT_MILLIS components.gateway.apiml.gateway.ti

APIML_MAX_CONNECTIONS_PER_ROUTE components.gateway.server.maxConnec

APIML_MAX_TOTAL_CONNECTIONS components.gateway.server.maxTotalC

APIML_PREFER_IP_ADDRESS Removed in v2
APIML_SECURITY_AUTH_PROVIDER components.gateway.apiml.security.a

APIML_SECURITY_AUTHORIZATION_ENDPOINT_URL components.gateway.apiml.security.a

APIML_SECURITY_X509_ENABLED components.gateway.apiml.security.x

APIML_SECURITY_ZOSMF_APPLID zOSMF.applId

CATALOG_PORT components.api-catalog.port
 Zowe v1 Variable Zowe v2 YAML Confi
DISCOVERY_PORT components.discovery.port

EXTERNAL_CERTIFICATE_AUTHORITIES zowe.certificate.pem.certificateAut

EXTERNAL_COMPONENTS Removed in v2

FILES_API_PORT components.files-api.port

GATEWAY_PORT components.gateway.port

INSTANCE_DIR Removed in v2

JAVA_HOME java.home

JES_EXPLORER_UI_PORT Removed in v2

JOBS_API_PORT components.jobs-api.port

KEY_ALIAS zowe.certificate.keystore.alias

KEYSTORE_CERTIFICATE_AUTHORITY zowe.certificate.pem.certificateAut

KEYSTORE_CERTIFICATE zowe.certificate.pem.certificate

KEYSTORE_DIRECTORY zowe.setup.certificate.pkcs12.direc
 Zowe v1 Variable Zowe v2 YAML Confi
KEYSTORE_KEY zowe.certificate.pem.key

zowe.certificate.keystore.password
KEYSTORE_PASSWORD
zowe.certificate.truststore.passwor

KEYSTORE_TYPE
zowe.certificate.keystore.type and
zowe.certificate.truststore.type

KEYSTORE zowe.certificate.keystore.file

LAUNCH_COMPONENT_GROUPS Removed in v2

MVS_EXPLORER_UI_PORT Removed in v2

PKCS11_TOKEN_LABEL Removed in v2
PKCS11_TOKEN_NAME Removed in v2
ROOT_DIR zowe.runtimeDirectory

SKIP_NODE Removed in v2

STATIC_DEF_CONFIG_DIR -

TRUSTSTORE zowe.certificate.truststore.file

USS_EXPLORER_UI_PORT Removed in v2
 Zowe v1 Variable Zowe v2 YAML Confi
ZOSMF_HOST zOSMF.host

ZOSMF_PORT zOSMF.port

ZOWE_APIM_NONSTRICT_VERIFY_CERTIFICATES zowe.verifyCertificates

ZOWE_APIM_VERIFY_CERTIFICATES zowe.verifyCertificates

ZOWE_EXPLORER_FRAME_ANCESTORS Removed in v2

ZOWE_EXPLORER_HOST zowe.externalDomains or haInstances.

ZOWE_INSTANCE Removed in v2

ZOWE_IP_ADDRESS Removed in v2

ZOWE_PREFIX zowe.job.prefix

ZOWE_ZLUX_SECURITY_TYPE -
ZOWE_ZLUX_SERVER_HTTPS_PORT -
 Zowe v1 Variable Zowe v2 YAML Confi
ZOWE_ZLUX_SSH_PORT -
ZOWE_ZLUX_TELNET_PORT -
ZOWE_ZSS_SERVER_PORT -
ZOWE_ZSS_SERVER_TLS -
ZOWE_ZSS_XMEM_SERVER_NAME -
ZWE_CACHING_EVICTION_STRATEGY components.caching-service.storage.

ZWE_CACHING_SERVICE_PERSISTENT components.caching-service.storage.

ZWE_CACHING_SERVICE_PORT components.caching-service.port

ZWE_CACHING_SERVICE_VSAM_DATASET components.caching-service.storage.

ZWE_CACHING_STORAGE_SIZE components.caching-service.storage.

ZWE_DISCOVERY_SERVICES_LIST -

ZWE_DISCOVERY_SERVICES_REPLICAS components.discovery.replicas

ZWE_EXTENSION_DIR zowe.extensionDirectory

ZWE_EXTERNAL_HOSTS zowe.externalDomains

ZWE_EXTERNAL_PORT zowe.externalPort
 Zowe v1 Variable Zowe v2 YAML Confi

ZWE_LAUNCH_COMPONENTS
Combined information of components.<comp
true

ZWE_LOG_LEVEL_ZWELS zowe.launchScript.logLevel

ZWEAD_EXTERNAL_STATIC_DEF_DIRECTORIES Removed in v2

ZWES_ZIS_LOADLIB zowe.setup.dataset.authLoadlib

ZWES_ZIS_PARMLIB_MEMBER -
ZWES_ZIS_PARMLIB zowe.setup.dataset.parmlib

ZWES_ZIS_PLUGINLIB zowe.setup.dataset.authPluginLib

Packaging one component deliverable for both Zowe v1 and

v2
It is recommended that you create a dedicated package of extensions for Zowe v2, which is the most
straight-forward way to address all of the breaking changes introduced in v2. We understand that this
method presents the challenge of maintaining two sets of packages. If you prefer not to maintain two sets of
packages, it's still possible to maintain one version of an extension which works for both Zowe v1 and v2.
However, the lifecycle code will be complicated and in this case, comprehensive testing should be
performed.
CAUTION
 The Zowe v2 App Framework desktop is upgraded from Angular version 6 to angular version 12 for
support and security - websites have a "1 version of a library" limitation. This means that plug-ins
dependent upon Angular must be coded for either v6 or v12 [not both] thus the single version approach
is not applicable.
If the lifecycle scripts are the main concern, the following steps outline requirements and recommendations
for the single version approach:
Packaging manifest.yaml is required. This is a hard requirement for Zowe v2. If you define lifecycle
scripts with default names, for example, use bin/start.sh as commands.start , it should work
for v1.
Revisit all environment variables used in the lifecycle scripts and apply fallback variables. For example, if
you use $ROOT_DIR in Zowe v1, this should be changed to
${ZWE_zowe_runtimeDirectory:-${ROOT_DIR}} to make it compatible with both versions. Other
variables like $EXPLORER_HOST should be changed to
${ZWE_haInstance_hostname:-${EXPLORER_HOST}} or
${ZWE_externalDomains_0:-${EXPLORER_HOST}} based on purpose.

In Zowe v2, we recommend you to define extension configurations in the manifest.yaml configs
section and use ${ZWE_configs_*} variables to access them. This feature does not exist in Zowe
v1. So if you use ${ZWE_configs_*} variables, it should fall back to the matching environment
variable used in v1.
In Zowe v2, we recommend you to define a commands.install lifecycle script to handle extension
installation. This lifecycle script will be executed by zwe components install . In v1, this also exists
if you use the zowe-install-components.sh utility to install a Zowe extension. So if you want one
extension package to work for both Zowe v1 and v2, this install lifecycle script should also be
compatible with both v1 and v2.
A new v2 variable ${ZWE_VERSION} may help you determine the Zowe version number. This variable
does not exist in Zowe v1. By knowing the Zowe version, the lifecycle scripts can implement logic to
source v1 or v2 dedicated scripts to avoid handling fallbacks in the same script. This could help avoid
complicated compatibility version checks, and it could be easier in the future if you decide to drop Zowe
v1.
Zowe learning resources
Version: v2.0.x LTS

Learn more about Zowe from these blog posts, videos, and other resources.

Blogs
Zowe blogs on Medium
Zowe blogs on Open Mainframe Project website
Want to contribute a blog? Details for how to contribute to the Zowe blogs on Medium site are at Zowe Blog
Guidelines.

Videos

As well as Zowe videos owned and managed by the community, there are a number of external youtubers
who host Zowe related content.
Zowe Demos playlist from Bill Pereira
Mainframe Bytes channel from Jessielaine Punongbayan
Webinars
Find out what's happening with Zowe in the Zowe Quarterly Update Webinar Series.
Zowe Quarterly Update Webinar: October 2021
Zowe Quarterly Update Webinar: July 2021
Zowe Quarterly Update Webinar: April 2021
Zowe Quarterly Update Webinar: January 2021
Zowe Quarterly Update Webinar: October 2020
The OMP Youtube channel also offers other webinars about Zowe.
Treat Yourself to a Guided, Comprehensive Tour of Zowe Desktop Applications
Zowe Webinar Feb. 22, 2019
Open Mainframe Project Webinar: Zowe Virtual Hackathon

Community
Join us on Slack
Slack invite link
Introduction to Zowe Slack channels
Learn more about the community
Zowe community GitHub repo
Find out information about Zowe sub-projects, GitHub repos, mailing lists, community meeting minutes,
contribution guidelines, and so on.
Connect with the community through meetings
Zowe meeting calendar
You can join one of the Zowe meetings to get latest Zowe updates and get involved in different squads
and initiatives.

Training
Courses
Zowe Fundamentals
Interskill Learning offers a free training course that introduces the components that comprise Zowe and
the benefits of using Zowe and how its capabilities can be extended.
Trials
Zowe trial
The Zowe trial hosted by IBM is a fully configured z/OS environment with Zowe preinstalled and set up
along with a set of integrated easy-to-follow tutorials that walk you through the basics of Zowe and
gives you hands-on experience of extending Zowe. This no-charge trial is available in two hours for
three days.
Get started with the Zowe Web UI
This online tutorial hosted by IBM guides you to add new apps to the Zowe Web UI. It provides a public
hosted Zowe instance that allows you to perform the steps in a z/OS environment.
Overview
Version: v2.0.x LTS

The installation of Zowe™ consists of the following processes:

installation of the Zowe server components.
You can install the components either on z/OS only or you can install the components both on z/OS and
on Docker.
installation of Zowe CLI on a desktop computer.
The Zowe server components provide a web desktop that runs a number of applications such as API
Mediation Layer that includes the Single Sign-on (SSO) capability, organization of the multiple Zowe servers
under a single website, and other useful features for z/OS developers.
Because Zowe is a set of components, before installing Zowe, use this guide to determine which
components you want to install and where you want to install them.
Consider the following scenarios:
If you plan to use Zowe CLI on PC only, you may not need to install the Zowe server components.
Note: Some CLI plug-ins require the installation of components on z/OS. If you plan to use core Zowe
CLI groups from your PC, the z/OS you connect to does not require any components of Zowe to be
installed on z/OS, unless you want to take advantage of advanced authentication methods such as
single sign-on or multi-factor authentication.
If you use the Docker technical preview to run the Linux parts of Zowe in a container, you only need to
configure the Zowe z/OS component to start the ZSS server.
Installation roadmap
Version: v2.0.x LTS

When you install Zowe™ on z/OS, you install the following two parts:
. The Zowe runtime, which consists of a number of components including:
Zowe Application Framework
Zowe API Mediation Layer
Z Secure Services (ZSS)
. The Zowe Cross Memory Server, also known as ZIS, which is an APF authorized server application that
provides privileged services to Zowe in a secure manner.
Zowe provides the ability for some of its unix components to be run not under USS, but as a container, see
Installing Zowe Containers.
If you want to configure Zowe for high availability, see Installing Zowe z/OS Components with High
Availability for instructions.

Stage 1: Plan and prepare

Before you start the installation, review the information on hardware and software requirements and other
considerations. See Planning the installation for details.

Stage 2: Install the Zowe z/OS runtime

. Ensure that the software requirements are met. The prerequisites are described in System
requirements.
. Choose the method of installing Zowe on z/OS.
The Zowe z/OS binaries are distributed in the following formats. They contain the same contents but
you install them by using different methods. You can choose which method to use depending on your
needs.
Convenience build
 The Zowe z/OS binaries are packaged as a PAX file which is a full product install. Transfer this to a
USS directory and expand its contents. The command zwe install will extract a number of
PDS members contain load modules, JCL scripts, and PARMLIB entries.
SMP/E build
The Zowe z/OS binaries are packaged as the following files that you can download. You install this
build through SMP/E.
A pax.Z file, which contains an archive (compressed copy) of the FMIDs to be installed.
A readme file, which contains a sample job to decompress the pax.Z file, transform it into a
format that SMP/E can process, and invoke SMP/E to extract and expand the compressed
SMP/E input data sets.
Portable Software Instance (PSWI)
You can acquire and install the Zowe z/OS PAX file as a portable software instance (PSWI) using
z/OSMF.
While the procedures to obtain and install the convenience build, SMP/E build or PSWI are different, the
procedure to configure a Zowe runtime is the same irrespective of how the build is obtained and
installed.
. Obtain and install the Zowe build.
For how to obtain the convenience build and install it, see Installing Zowe runtime from a
convenience build.
For how to obtain the SMP/E build and install it, see Installing Zowe SMP/E.
For how to obtain the PSWI and install it, see Installing Zowe from a Portable Software Instance.
After successful installation of either a convenience build or an SMP/E build, there will be a zFS folder that
contains the unconfigured Zowe runtime directory, a utility library SZWEEXEC that contains utilities, a
SAMPLIB library SZWESAMP that contains sample members, and a load library SZWEAUTH that contains
load modules. The steps to prepare the z/OS environment to launch Zowe are the same irrespective of the
installation method.

Stage 3: Configure the Zowe z/OS runtime

You can configure the Zowe runtime with one of the following methods depending on your needs.
 Use a combination of JCL and the zwe init command
Use z/OSMF Workflows
Tip: We recommend you open the links to this configuration procedure in new tabs.
Whether you have obtained Zowe from a .pax convenience build, or an SMP/E distribution, the steps to
initialize the system are the same.
. Prepare custom MVS data sets. Copy the data sets provided with Zowe to custom data sets.
. (Required only if you are configuring Zowe for cross LPAR sysplex high availability): Create the VSAM
data sets used by the Zowe API Mediation Layer caching service.
. APF authorize load libraries containing the modules that need to perform z/OS priviledged security
calls..
. Initialize Zowe security configurations. Create the user IDs and security manager settings.
If Zowe has already been launched on a z/OS system from a previous release of Zowe v2 you can skip
this security configuration step unless told otherwise in the release documentation.
. Configure Zowe to use TLS certificates.
. Install Zowe main started tassks.

Looking for troubleshooting help?

If you encounter unexpected behavior when installing or verifying the Zowe runtime on z/OS, see the
Troubleshooting section for tips.
Planning the installation
Version: v2.0.x LTS

The following information is required during the Zowe installation process. Software and hardware
prerequisites are covered in the next section.
The zFS directory where you will install the Zowe runtime files and folders. For more details of setting up
and configuring the UNIX Systems Services (USS) environment, see UNIX System Services
considerations for Zowe.
A HLQ that the installation can create a load library and samplib containing load modules and JCL
samples required to run Zowe.
Multiple instances of Zowe can be started from the same Zowe z/OS runtime. Each launch of Zowe has
its own configuration, usually mentioned as Zowe YAML configuration file or zowe.yaml, and zFS
directory that is known as a workspace directory.
For Zowe in a high availability configuration, there will be only one workspace directory which must be
created on a shared file system (zFS directory) where all LPARs in a Sysplex can access.
(If not using containerization) Zowe optionally uses a zFS directory to contain its northbound certificate
keys as well as a truststore for its southbound keys if the administrator chooses to use PKCS#12
keystore for certificate storage. Northbound keys are one presented to clients of the Zowe desktop or
Zowe API Gateway, and southbound keys are for servers that the Zowe API gateway connects to. The
certificate directory is not part of the Zowe runtime so that it can be shared between multiple Zowe
runtimes and have its permissions secured independently.
Zowe has the following started tasks:
ZWESISTC is a cross memory server that the Zowe desktop uses to perform APF-authorized
code. More details on the cross memory server are described in Configuring the Zowe cross
memory server.
ZWESASTC is a cross memory Auxiliary server that is used under some situations in support of a
Zowe extension. Auxiliary server is started, controlled, and stopped by the cross memory server, so
no need to start it manually. More details are described in Zowe auxiliary service
ZWESLSTC brings up other parts of the Zowe runtime on z/OS as requested. This may include
Desktop, API mediation layer, ZSS, and more, but when using containerization likely only ZSS will
 be used here. It can be used for a single Zowe instance deployment and can also be used for Zowe
high availability deployment in Sysplex. It brings up and stops Zowe instances, or specific Zowe
components without restarting the entire Zowe instances.
In order for above started tasks to run correctly, security manager configuration needs to be
performed. This is documented in Configuring the z/OS system for Zowe and a sample JCL
member ZWESECUR is shipped with Zowe that contains commands for RACF, TopSecret, and
ACF2 security managers.
Notes:
To start the API Mediation Layer as a standalone component, see API Mediation Layer as a
standalone component.
If you plan to use API ML with basic authentication and JSON web token authentication, you need
to run only ZWESLSTC . No need to run ZWESISTC and ZWESASTC .
If you plan to use API ML with x509 client-side certificate authentication, you need to run
ZWESISTC and ZWESLSTC .

Topology of the Zowe z/OS launch process

Runtime directory
The runtime directory contains the binaries and executable files. You can create a runtime directory in one of
the following ways:
Create a directory and extract Zowe convenience build into it.
Installing the Zowe SMP/E FMID AZWE002 using the JCL members in the REL4 member.
Executing the z/OSMF worklow script ZWERF01 contained in the SMP/E FMID AZWE002.
During execution of Zowe, the runtime directory contents are not modified. Maintenance or APAR release for
Zowe replaces the contents of the runtime directory and are rollup PTFs.
A typical Zowe runtime directory looks like this:
zwe server command
The zwe command is provided in the <RUNTIME_DIR>/bin directory. You can use this command and
sub-commands to initialize Zowe, manage Zowe instances and fulfill common tasks.
The zwe command has built in help that can be retrieved with the -h suffix. For example, type zwe -h
to display all of the supported commands. These are broken down into a number of sub-commands.
Other useful global parameters are:
--debug or -v to enable verbose mode.

--trace or -vv to enable trace mode for current command.

--log-dir or -l to also write output to log files.

Add the zwe command to your PATH

You can add this Zowe bin directory to your PATH environment variable so you can execute the zwe
command without having to fully qualify its location. To update your PATH, run the following command:
This will update the PATH for the current shell. To make this update persistent, you can add the line to your
~/.profile file, or the ~/.bashProfile file if you are using a bash shell. To make this update system
wide, you can update the /etc/.profile file. Once the PATH is updated, you can execute the zwe
command from any USS directory. For the remainder of the documentation when zwe command is
referenced, it is assumed that it has been added to your PATH .
z/OS Data sets used by Zowe
After Zowe is properly installed, you should have these data sets created on z/OS under the prefix you
defined:
<prefix>.SZWEAUTH contains few Zowe component programs to start Zowe and ZSS.

<prefix>.SZWEEXEC contains few utility executables will be used by Zowe.

<prefix>.SZWESAMP contains sample JCLs to help you configure or start Zowe.

If you install Zowe with convenience build, these data sets will be created by zwe install command. If
you install Zowe with SMPE or equivalent methods, these data sets will be created during install and you are
not required to run zwe install command. The above data sets will be overwritten during upgrade
process.
Zowe configuration and runtime also use few other data sets to store customization. These data sets will not
be overwritten during upgrade.
zowe.setup.datasets.parmlib defined in Zowe configuration, which contains user customized
PARMLIB members.
zowe.setup.datasets.jcllib defined in Zowe configuration, which contains user customized
JCLs or JCLs generated by zwe init command.
zowe.setup.datasets.authLoadlib defined in Zowe configuration is optional. If the user choose
to copy out load libraries from <prefix>.SZWEAUTH , they will be placed here. With this option, you
have better control on what will be APF authorized other than authorize whole <prefix>.SZWEAUTH .
zowe.setup.datasets.authPluginLib defined in Zowe configuration contains extra load libraries
used by ZIS plugins.
Zowe configuration file
Zowe uses a YAML format configuration. If you store the configuration on USS, this file is usually referred as
zowe.yaml .

This configuration file can be placed on a location with these requirements:

Zowe runtime user, usually referred as ZWESVUSR , must have read permission to this file.
If you plan to run Zowe in Sysplex, all Zowe high availability instances must share the same
configuration file. That means this configuration file should be placed in a shared file system (zFS
directory) where all LPARs in a Sysplex can access.
Zowe configuration file may contain sensitive configuration information so it should be protected
against malicious accessing.
To create this configuration, you can copy from example-zowe.yaml located in Zowe runtime directory.
Please be aware of the zowe.runtimeDirectory definition in the configuration file, it should match the
Zowe runtime directory mentioned above.
To learn more about this configuration, please check Zowe YAML configuration file reference.
When you execute the zwe command, the --config or -c argument is used to pass the location of a
zowe.yaml file.

TIP
 To avoid passing --config or -c to every zwe commands, you can define
ZWE_CLI_PARAMETER_CONFIG environment variable points to location of zowe.yaml.

For example, after defining

, you can simply type zwe start instead of full command zwe start -c
/path/to/my/zowe.yaml .

Workspace directory
The workspace directory is required to launch Zowe. It is automatically created when you start Zowe. More
than one workspace directory can be created and used to launch multiple instances of Zowe sharing the
same runtime directory. It's not recommended to create workspace directory manually in order to avoid
permission conflicts.
Zowe instances are started by running the server command zwe start . This creates a started task with
the PROCLIB member ZWESLSTC that is provided with the samplib SZWESAMP created during the
installation of Zowe. The JCL member ZWESLSTC starts Zowe launcher under which it launches Zowe
components address spaces.
Zowe enables read and write permission to both Zowe runtime user ( ZWESVUSR by default) and Zowe
admin group ( ZWEADMIN by default) for Zowe workspace directory.
If you plan to run Zowe in Sysplex, all Zowe high availability instances must share the same workspace
directory, which means it should be placed in a shared file system (zFS directory) where all LPARs in a
Sysplex can access.
The workspace directory should be defined in your Zowe configuration file as
zowe.workspaceDirectory .

Log directory
Some Zowe components will write logs to file system. The directory will be created automatically when you
start Zowe and the content will be automatically managed by Zowe components. It's not recommended to
create log directory manually in order to avoid permission conflicts.
Multiple Zowe instances can define different log directories, they are not necessary to be shared in Sysplex
deployment like workspace directory.
The log directory should be defined in your Zowe configuration file as zowe.logDirectory .
Keystore directory
Zowe uses certificates to enable transport layer security. The system administrator can choose to use z/OS
Keyring or PKCS#12 keystore for certificate storage. A keystore directory will be created and used if
PKCS#12 keystore is chosen.
A typical PKCS#12 keystore directory looks like:
To generate keystore directory, you need proper zowe.setup.certificate configuration defined in
Zowe configuration file and then execute server command zwe init certificate . To learn more about
this command, check Reference of zwe init certificate.
Extension directory
Zowe allows server extensions to expand its core functionalities. The extensions are required to be installed
in a central location so Zowe runtime can find and recognize them.
Similar to Zowe runtime directory, this extension directory should be created by the administrators perform
Zowe installation and configuration task. Zowe runtime user, typically ZWESVUSR requires read-only
permission to this directory.
The extension directory should be created by system administrator and defined in your Zowe configuration
file as zowe.extensionDirectory .
Zowe uses zwe components install command to install Zowe server extensions. This command will
create sub-directories or symbolic links under the extension directory.
UNIX System Services considerations for
Version: v2.0.x LTS

Zowe
The Zowe z/OS component runtime requires USS to be configured. As shown in the Zowe architecture, a
number of servers run under UNIX System Services (USS) on z/OS. Review this topic for knowledge and
considerations about USS when you install and configure Zowe.
Introduction
Setting up USS for the first time
Language environment
OMVS segment
Address space region size

What is USS?
The UNIX System Services element of z/OS® is a UNIX operating environment, which is implemented within
the z/OS operating system. It is also known as z/OS UNIX. z/OS UNIX files are organized in a hierarchy, as in
a UNIX system. All files are members of a directory, and each directory in turn is a member of another
directory at a higher level in the hierarchy. The highest level of the hierarchy is the root directory. The z/OS
UNIX files system is also known as zFS.
For more information on USS, see the following resources:
Introduction to z/OS UNIX for z/OS 2.2
Introduction to z/OS UNIX for z/OS 2.3
Introduction to z/OS UNIX for z/OS 2.4

Setting up USS for the first time

If you have not enabled USS for your z/OS environment before, the SMP/E distribution of Zowe provides a
number of JCL jobs to assist with this purpose. You can consult with your USS administrator if you need
more information such as the USS file system.
Language environment
To ensure that Zowe has enough memory, the recommended HEAP64 site should be large enough.

OMVS segment
Users who install Zowe to run Zowe scripts need to have an OMVS segment. If the user profile doesn't have
OMVS segment, the following situations might occur:
When you access USS through TSO OMVS, you will see the following message:
When you access USS through SSH, you will see the following message:

Address space region size

Java as a prerequisite for Zowe requires a suitable z/OS region size to operate successfully while you install
and configure Zowe. It is suggested that you do not restrict the region size, but allow Java to use what is
necessary. Restricting the region size might cause failures with storage-related error messages such as the
following one:
You can fix the storage-related issue by making one of the following changes:
ASSIZEMAX parameter
The ASSIZEMAX parameter is the maximum size of the process's virtual memory (address space) in
bytes.
To specify the JVM maximum address space size on a per-user basis, set the ASSIZEMAX configuration
parameter to the value of 2147483647 .
Note: Running a shell script via TSO OMVS will run the shell in the TSO address space, unless you
specify _BPX_SHAREAS=NO when invoking OMVS. If you are using TSO OMVS to install Zowe, you will
need export _BPX_SHAREAS=NO to make the ASSIZEMAX change effective.
SIZE parameter of TSO segment
Set SIZE operand of TSO segment to the value of 2096128 .
Note: If you set export _BPX_SHAREAS=YES in your shell setup as recommended, Java will run in
the TSO address space and the SIZE change will work.
ulimit -A

The maximum address space size for the process should be at least 250 M, in units of 1024 bytes. For
example, ulimit -A 250000 .
Note: Running ulimit -a displays the current process limits.
System requirements
Version: v2.0.x LTS

Before installing Zowe™ z/OS components, ensure that your z/OS environment meets the prerequisites. The
prerequisites you need to install depend on what Zowe z/OS components you want to use and how you want
to install and configure Zowe on z/OS. Therefore, assess your installation scenario and install the
prerequisites that meet your needs.
All Zowe server components can be installed on a z/OS environment, while some can alternatively be
installed on Linux or zLinux via Docker. The components provide a number of services that are accessed
through a web browser such as an API catalog and a web desktop.
z/OS system requirements
z/OS
Node.js
Java
z/OSMF (Optional)
User ID requirements
ZWESVUSR
ZWESIUSR
ZWEADMIN
zowe_user
Network requirements
Zowe Containers requirements
Zowe Desktop requirements (client PC)
Feature requirements
Multi-Factor Authentication MFA
Single Sign-On SSO
Memory requirements

z/OS system requirements

Be sure your z/OS system meets the following prerequisites.
z/OS
 z/OS version in active support, such as Version 2.3 and Version 2.4
Note: z/OS V2.2 reached end of support on 30 September 2020. For more information, see the z/OS
v2.2 lifecycle details https://www.ibm.com/support/lifecycle/details?q45=Z497063S01245B61.
zFS volume with at least 833 mb of free space for Zowe server components, their keystore, instance
configuration files and logs, and third-party plug-ins.
(Optional, recommended) z/OS OpenSSH V2.2.0 or later
Some features of Zowe require SSH, such as the Desktop's SSH terminal. Or, you want to install and
manage Zowe via SSH, as an alternative to OMVS over TN3270.
(Optional, recommended) Parallel Sysplex.
To deploy Zowe for high availability, a Parallel Sysplex environment is recommended. Please check
Configuring Sysplex for high availability for more information.
Node.js
Node.js v12.x, v14.x (except v14.17.2), or v16.x
Node is not included with z/OS so must be installed separately. To install Node.js on z/OS, follow the
instructions in Installing Node.js on z/OS.
Note: If you are a software vendor building extensions for Zowe, when using Node.js v12.x or later, it is
highly recommended that plug-ins used are tagged. For more information, see Tagging on z/OS.
Java
IBM SDK for Java Technology Edition V8
z/OSMF (Optional)
(Optional, recommended) IBM z/OS Management Facility (z/OSMF) Version 2.2, Version 2.3 or Version
2.4.
z/OSMF is included with z/OS so does not need to be separately installed. If z/OSMF is present, Zowe
will detect this when it is configured and use z/OSMF for the following purposes:
 Authenticating TSO users and generating a single sign-on JSON Web Token (JWT). Ensure that the
z/OSMF JWT Support is available via APAR and associated PTFs. If z/OSMF is not available, then
Zowe is still able to provide SSO by generating its own JWT and making direct SAF calls.
REST API services for Files (Data Sets and USS), JES, and z/OSMF workflows. These are used by
some Zowe applications such as the Zowe Explorers in the Zowe Desktop. If z/OSMF REST APIs are
not present, other Zowe desktop application, such as the File Editor that provides access to USS
directories and files as well as MVS data sets and members, will work through the Zowe Z Secure
Services (ZSS) component to access z/OS resources.
Tips:
For non-production use of Zowe (such as development, proof-of-concept, demo), you can
customize the configuration of z/OSMF to create what is known as "z/OS MF Lite" that simplifies
the setup of z/OSMF. As z/OS MF Lite only supports selected REST services (JES, DataSet/File,
TSO and Workflow), you will observe considerable improvements in startup time as well as a
reduction in the efforts involved in setting up z/OSMF. For information about how to set up z/OSMF
Lite, see Configuring z/OSMF Lite (non-production environment).
For production use of Zowe, see Configuring z/OSMF.

User ID requirements
Specific user IDs with sufficient permissions are required to run or access Zowe.
ZWESVUSR
This is a started task ID for ZWESLSTC .
The task starts a USS environment using BPXBATSL that executes the core Zowe Desktop (ZLUX) node.js
server, the Java API Mediation Layer, and the Z Secure Services C component. To work with USS, the user ID
ZWESVUSR must have a valid OMVS segment.

Class ID Access Reason

CSFSERV READ To generate symmetric keys using ICSF that is

CSFRNGL
used by Zowe Desktop cookies
 Class ID Access Reason

FACILITY READ To allow Zowe ZWESVSTC processes to access

ZWES.IS
the Zowe ZIS cross memory server
To allow the Zowe Desktop ZLUX server to run
FACILITY BPX.SERVER + UPDATE code on behalf of the API requester's TSO user
BPX.DAEMON ID. For more information, see Security
Environment Switching.
FACILITY READ To allow Zowe to map an X.509 client certificate
IRR.RUSERMAP
to a z/OS identity
To allow z/OS address spaces for unix
FACILITY BPX.JOBNAME READ processes to be renamed for ease of
identification
To allow Zowe to obtain information about
FACILITY IRR.RADMIN.LISTUSER READ OMVS segment of the user profile using
LISTUSER TSO command

APPL 'OMVSAPPL' READ Optional To allow Zowe Desktop vendor

extensions the ability to use single-sign on.

ZWESIUSR
This is a started task ID used to run the PROCLIB ZWESISTC that launches the cross memory server (also
known as ZIS). It must have a valid OMVS segment.
ZWEADMIN
This is a group that ZWESVUSR and ZWESIUSR should belong to. It must have a valid OMVS segment.
zowe_user
If z/OSMF is used for authentication and serving REST APIs for Zowe CLI and Zowe Explorer users, the TSO
user ID for end users must belong to one or both of the groups IZUUSER or IZUADMIN .
Network requirements
The following ports are required for Zowe. These are default values. You can change the values by updating
variable values in the zowe.yaml file.
Port zowe.yaml variable name Purpose
number

7552 zowe.components.api- Used to view API swagger / openAPI specifications for

catalog.port registered API services in the API Catalog.
7553 zowe.components.api- Discovery server port which dynamic API services can
catalog.port issue APIs to register or unregister themselves.
The northbound edge of the API Gateway used to
accept client requests before routing them to registered
7554 zowe.components.gateway.port API services. This port must be exposed outside the
z/OS network so clients (web browsers, VS Code,
processes running the Zowe CLI) can reach the gateway.
zowe.components.caching- Port of the caching service that is used to share state
7555 service.port between different Zowe instances in a high availability
topology.
7556 zowe.components.app- The Zowe Desktop (also known as ZLUX) port used to
server.port log in through web browsers.
Z Secure Services (ZSS) provides REST API services to
7557 zowe.components.zss.port ZLUX, used by the File Editor application and other ZLUX
applications in the Zowe Desktop.
7558 zowe.components.jobs-api.port Port of the service that provides REST APIs to z/OS jobs
used by the JES Explorer.
7559 zowe.components.files-api.port Port of the service that provides REST APIs to MVS and
USS file systems.
 Port zowe.yaml variable name Purpose
number

zowe.components.explorer-jes Port of the JES Explorer GUI for viewing and working
with jobs in the Zowe Desktop.
zowe.components.explorer- Port of the MVS Explorer GUI for working with data sets
mvs in the Zowe Desktop.
zowe.components.explorer-uss Port of the USS Explorer GUI for working with USS in the
Zowe Desktop.

Zowe Containers requirements

Zowe (server) containers are available for download as an alternative to running Zowe servers on z/OS
through the Zowe convenience and SMP/E builds Check Zowe Containers Prerequisites page for more
details.

Zowe Desktop requirements (client PC)

The Zowe Desktop is powered by the Application Framework which has server prereqs depending on where
it is installed
Zowe Application Framework on z/OS requirements
Application Framework on Docker prerequisites
The Zowe Desktop runs inside of a browser. No browser extensions or plugins are required. The Zowe
Desktop supports Google Chrome, Mozilla Firefox, Apple Safari and Microsoft Edge releases that are at most
1 year old, except when the newest release is older. For Firefox, both the regular and Extended Support
Release (ESR) versions are supported under this rule.
Currently, the following browsers are supported:
Google Chrome V79 or later
Mozilla Firefox V68 or later
Safari V13 or later
 Microsoft Edge 79
If you do not see your browser listed here, please contact the Zowe community so that it can be validated
and included.

Feature requirements
Zowe has several optional features that have additional prerequisites as follows.
Multi-Factor Authentication (MFA)
Multi-factor authentication is supported for several components, such as the Desktop and API Mediation
Layer. Multi-factor authentication is provided by third-party products which Zowe is compatible with. The
following are known to work:
IBM Z Multi-Factor Authentication.
Note: To support the multi-factor authentication, it is necessary to apply z/OSMF APAR PH39582.
For information on using MFA in Zowe, see Multi-Factor Authentication.
Note: MFA must work with Single sign-on (SSO). Make sure that SSO is configured before you use MFA in
Zowe.
Single Sign-On (SSO)
Zowe has an SSO scheme with the goal that each time you use multiple Zowe components you should only
be prompted to login once.
Requirements:
IBM z/OS Management Facility (z/OSMF)

Memory requirements
Zowe API ML components have following memory requiremets:
Component name Memory usage
Component name Memory usage
Gateway service 256MB
Discovery service 256MB
API Catalog 512MB
Metrics service 512MB
Caching service 512MB
(Optional, recommended) PKCS#11 token setup is required when using ZSS, the Desktop, and
Application Framework with SSO. See Creating a PKCS#11 Token for more information.
Installing Node.js on z/OS
Version: v2.0.x LTS

Note: This section is not required if using Docker or only using the CLI.
Before you install Zowe™ on z/OS, you must install IBM SDK for Node.js on the same z/OS server that hosts
the Zowe Application Server and z/OS Explorer Services. Review the information in this topic to obtain and
install Node.js.
Supported Node.js versions
How to obtain IBM SDK for Node.js - z/OS
Hardware and software prerequisites
Installing the PAX edition of Node.js - z/OS
Installing the SMP/E edition of Node.js - z/OS

Supported Node.js versions

The following Node.js versions are supported to run Zowe. See the Hardware and software prerequisites
section for the prerequisites that are required by Zowe.
The corresponding IBM Knowledge Center for Node.js - z/OS lists all the prerequisites for Node.js. Some
software packages, which might be listed as prerequisites there, are NOT required by Zowe. Specifically, you
do NOT need to install Python, Make, Perl, or C/C++ runtime or compiler. If you can run node --version
successfully, you have installed the prerequisites required by Zowe.
Notice: IBM SDK for node.js had withdrawn v8 from marketing on September 7, 2020 and ended v8 service
on September 30, 2021. Zowe ended support for node v8.x in January 2022.
v12.x
z/OS V2R2: PTFs UI62788, UI46658, UI62416, UI62415 (APARs PH10606, PI79959, PH10740,
PH10741)
z/OS V2R3: PTFs UI61308, UI61375, UI61747 (APARs PH0710, PH08352, PH09543)
z/OS V2R4: PTFs UI64839, UI64940, UI64837, UI64830 , UI65567 (APARs PH14559, PH16038,
PH15674, PH14560, PH17481)
v14.x (except v14.17.2)
 z/OS V2R3: PTFs UI61308, UI61375, UI61747 (APARs PH07107, PH08352, PH09543)
z/OS V2R4: PTFs UI64830, UI64837, UI64839, UI64940, UI65567 (APARs PH14560, PH15674,
PH14559, PH16038, PH17481)
Known issue: There is a known issue with node.js v14.17.2. It will cause the error of ZWESLSTC
not found in "<dsn-prefix>.SZWESAMP" when you run the zowe-install-proc.sh
utility.
v16.x
z/OS V2R4: PTFs UI64830, UI64837, UI64839, UI64940, UI65567.
z/OS V2R5: PTFs UI64830, UI64837,UI64940.

How to obtain IBM SDK for Node.js - z/OS

You can obtain IBM SDK for Node.js - z/OS for free in one of the following ways:
Use the PAX edition for non-production deployments which you can download from
ibm.com/products/sdk-nodejs-compiler-zos.
Order the SMP/E edition through your IBM representative for production use.
For more information, see the blog "How to obtain IBM SDK for Node.js - z/OS, at no charge".

Hardware and software prerequisites

To install Node.js for Zowe, the following requirements must be met.
The corresponding IBM Knowledge Center for Node.js - z/OS lists all the prerequisites for Node.js. Some
software packages, which might be listed as prerequisites there, are NOT required by Zowe. Specifically, you
do NOT need to install Python, Make, Perl, or C/C++ runtime or compiler.
If you can run node --version successfully, you have installed the Node.js prerequisites required by
Zowe.
Hardware:
IBM zEnterprise® 196 (z196) or newer
Software:
z/OS UNIX System Services enabled
Integrated Cryptographic Service Facility (ICSF) configured and started
ICSF is required for Node.js to operate successfully on z/OS. If you have not configured your z/OS
environment for ICSF, see Cryptographic Services ICSF: System Programmer's Guide. To see whether
ICSF has been started, check whether the started task ICSF or CSF is active.

Installing the PAX edition of Node.js - z/OS

Follow these steps to install the PAX edition of Node.js - z/OS to run Zowe.
. Download the pax.Z file to a z/OS machine.
. Extract the pax.Z file inside an installation directory of your choice. For example:
pax -rf <path_to_pax.Z_file> -x pax

. Add the full path of your installation directory to your PATH environment variable:
. Run the following command from the command line to verify the installation.
If Node.js is installed correctly, the version of Node.js is displayed.
. After you install Node.js, set the NODE_HOME environment variable to the directory where Node.js is
installed. For example, NODE_HOME=/proj/mvd/node/installs/node-v6.14.4-os390-s390x .

Installing the SMP/E edition of Node.js - z/OS

To install the SMP/E edition of Node.js, see the documentation for IBM SDK for Node.js - z/OS. Remember
that the software packages Perl, Python, Make, or C/C++ runtime or compiler that the Node.js
documentation might mention are NOT needed by Zowe.
Configuring z/OSMF
Version: v2.0.x LTS

The following information contains procedures and tips for meeting z/OSMF requirements. For complete
information, go to IBM Knowledge Center and read the following documents.
IBM z/OS Management Facility Configuration Guide
IBM z/OS Management Facility Help

z/OS requirements for z/OSMF configuration

Ensure that the z/OS system meets the following requirements:
Resources in
Requirements Description IBM
Knowledge
Center

AXR (System z/OS uses AXR (System REXX) component to perform Incident Log
REXX) tasks. The component enables REXX executable files to run outside System REXX
of conventional TSO and batch environments.
Common The CEA server, which is a co-requisite of the Common Information Customizing
Event Adapter Model (CIM) server, enables the ability for z/OSMF to deliver z/OS for CEA
(CEA) server events to C-language clients.
Common z/OSMF uses the CIM server to perform capacity-provisioning and Reviewing
Information workload-management tasks. Start the CIM server before you start your CIM
Model (CIM) z/OSMF (the IZU* started tasks). server setup
server
 Resources in
Requirements Description IBM
Knowledge
Center
Customizing
CONSOLE and The CONSOLE and CONSPROF commands must exist in the the
CONSPROF authorized command table. CONSOLE
commands and
CONSPROF
commands
IBM® 64-bit SDK for z/OS®, Java Technology Edition V8 or later is Software
Java level required. prerequisites
for z/OSMF

TSO region To prevent exceeds maximum region size errors, verify that the
size TSO maximum region size is a minimum of 65536 KB for the z/OS N/A
system.
User IDs require a TSO segment (access) and an OMVS segment.
User IDs During workflow processing and REST API requests, z/OSMF might N/A
start one or more TSO address spaces under the following job
names: userid; substr(userid, 1, 6) CN (Console).

Configuring z/OSMF
Follow these steps:
. From the console, issue the following command to verify the version of z/OS:
Part of the output contains the release, for example,
. Configure z/OSMF.
z/OSMF is a base element of z/OS V2.2 and V2.3, so it is already installed. But it might not be configured
and running on every z/OS V2.2 and V2.3 system.
 In short, to configure an instance of z/OSMF, run the IBM-supplied jobs IZUSEC and IZUMKFS, and then
start the z/OSMF server. The z/OSMF configuration process occurs in three stages, and in the following
order:
Stage 1 - Security setup
Stage 2 - Configuration
Stage 3 - Server initialization
This stage sequence is critical to a successful configuration. For complete information about how
to configure z/OSMF, see Configuring z/OSMF for the first time if you use z/OS V2.2 or Setting up
z/OSMF for the first time if V2.3.
Note: In z/OS V2.3, the base element z/OSMF is started by default at system initial program load (IPL).
Therefore, z/OSMF is available for use as soon as you set up the system. If you prefer not to start z/OSMF
automatically, disable the autostart function by checking for START commands for the z/OSMF started
procedures in the COMMNDxx parmlib member.
The z/OS Operator Consoles task is new in Version 2.3. Applications that depend on access to the operator
console such as Zowe™ CLI's RestConsoles API require Version 2.3.
. Verify that the z/OSMF server and angel processes are running. From the command line, issue the
following command:
If jobs IZUANG1 and IZUSVR1 are not active, issue the following command to start the angel process:
After you see the message ""CWWKB0056I INITIALIZATION COMPLETE FOR ANGEL"", issue the
following command to start the server:
The server might take a few minutes to initialize. The z/OSMF server is available when the message
""CWWKF0011I: The server zosmfServer is ready to run a smarter planet."" is displayed.
. Issue the following command to find the startup messages in the SDSF log of the z/OSMF server:
You could see a message similar to the following message, which indicates the port number:
In this example, the port number is 443. You will need this port number later.
Point your browser at the nominated z/OSMF STANDALONE Server home page and you should see its
Welcome Page where you can log in.
Note: If your implementation uses an external security manager other than RACF (for example, Top Secret
for z/OS or ACF2 for z/OS), you provide equivalent commands for your environment. For more information,
see the following product documentation:
Configure z/OS Management Facility for Top Secret
Configure z/OS Management Facility for ACF2

z/OSMF REST services for the Zowe CLI

The Zowe CLI uses z/OSMF Representational State Transfer (REST) APIs to work with system resources and
extract system data. Ensure that the following REST services are configured and available.

z/OSMF Resources in
REST Requirements IBM
services knowledge
Center
Cloud Cloud provisioning services are required for the Zowe CLI CICS and Cloud
provisioning Db2 command groups. Endpoints begin with provisioning
services /zosmf/provisioning/ services
TSO/E TSO/E
address TSO/E address space services are required to issue TSO commands in address
space the Zowe CLI. Endpoints begin with /zosmf/tsoApp space
services services
z/OS z/OS console services are required to issue console commands in the z/OS console
console Zowe CLI. Endpoints begin with /zosmf/restconsoles/ services
services
z/OS data z/OS data set and file REST interface is required to work with z/OS data set
set and file mainframe data sets and UNIX System Services files in the Zowe CLI. and file REST
REST Endpoints begin with /zosmf/restfiles/ interface
interface
 z/OSMF Resources in
REST Requirements IBM
services knowledge
Center
z/OS jobs z/OS jobs REST interface is required to use the zos-jobs command z/OS jobs
REST group in the Zowe CLI. Endpoints begin with /zosmf/restjobs/ REST
interface interface
z/OSMF z/OSMF workflow services is required to create and manage z/OSMF z/OSMF
workflow workflows on a z/OS system. Endpoints begin with workflow
services /zosmf/workflow/ services
Zowe uses symbolic links to the z/OSMF bootstrap.properties ,
jvm.security.override.properties , and ltpa.keys files. Zowe reuses SAF, SSL, and LTPA
configurations; therefore, they must be valid and complete.
For more information, see Using the z/OSMF REST services in IBM z/OSMF documentation.
To verify that z/OSMF REST services are configured correctly in your environment, enter the REST endpoint
into your browser. For example: https://mvs.ibm.com:443/zosmf/restjobs/jobs
Notes:
Browsing z/OSMF endpoints requests your user ID and password for defaultRealm; these are your TSO
user credentials.
The browser returns the status code 200 and a list of all jobs on the z/OS system. The list is in raw
JSON format.

Configuration of z/OSMF to properly work with API ML

There is an issue observed in z/OSMF which leads to a stuck JSON web token(JWT). It manifests as the
endpoint /zosmf/services/authenticate issuing a JWT with success RC that is not valid for API calls,
resulting in 401 response status code. This is a persistent condition. To get the token unstuck, perform a
logout with the LTPA token from the login request. This causes logins to start serving unique JWTs again.
Until this issue is properly fixed in z/OSMF, we propose a possible temporary workaround. Update z/OSMF
configuration with allowBasicAuthLookup="false" . After applying this change, each authentication
call results in generating a new JWT.
Configuring z/OSMF Lite (for non-production
Version: v2.0.x LTS

use)
This section provides information about requirements for z/OSMF Lite configuration.
Disclaimer: z/OSMF Lite can be used in a non-production environment such as development, proof-of-
concept, demo and so on. It is not for use in a production environment. To use z/OSMF in a production
environment, see Configuring z/OSMF.
Configuring z/OSMF Lite (for non-production use)
Introduction
Assumptions
Software Requirements
Minimum Java level
WebSphere® Liberty profile (z/OSMF V2R3 and later)
System settings
Web browser
Creating a z/OSMF nucleus on your system
Running job IZUNUSEC to create security
Before you begin
Procedure
Results
Common errors
Running job IZUMKFS to create the z/OSMF user file system
Before you begin
Procedure
Results
Common errors
Copying the IBM procedures into JES PROCLIB
Before you begin
Procedure
Results
 Common errors
Starting the z/OSMF server
Before you begin
Procedure
Results
Accessing the z/OSMF Welcome page
Before you begin
Procedure
Results
Common errors
Mounting the z/OSMF user file system at IPL time
Before you begin
Procedure
Results
Adding the required REST services
Enabling the z/OSMF JOB REST services
Procedure
Results
Common errors
Enabling the TSO REST services
Before you begin
Procedure
IZUTSSEC
Results
Enabling the z/OSMF data set and file REST services
Before you begin
Procedure
Results
Common errors
Enabling the z/OSMF Workflow REST services and Workflows task UI
Before you begin
Procedure
Results
Troubleshooting problems
 Common problems and scenarios
System setup requirements not met
Tools and techniques for troubleshooting
Common messages
Appendix A. Creating an IZUPRMxx parmlib member
Appendix B. Modifying IZUSVR1 settings
Appendix C. Adding more users to z/OSMF
Before you Begin
Procedure
Results
Appendix A. Creating an IZUPRMxx parmlib member
Appendix B. Modifying IZUSVR1 settings
Appendix C. Adding more users to z/OSMF

Introduction
IBM® z/OS® Management Facility (z/OSMF) provides extensive system management functions in a task-
oriented, web browser-based user interface with integrated user assistance, so that you can more easily
manage the day-to-day operations and administration of your mainframe z/OS systems.
By following the steps in this guide, you can quickly enable z/OSMF on your z/OS system. This simplified
approach to set-up, known as "z/OSMF Lite", requires only a minimal amount of z/OS customization, but
provides the key functions that are required by many exploiters, such as the open mainframe project
(Zowe™).
A z/OSMF Lite configuration is applicable to any future expansions you make to z/OSMF, such as adding
more optional services and plug-ins.
It takes 2-3 hours to set up z/OSMF Lite. Some steps might require the assistance of your security
administrator.
For detailed information about various aspects of z/OSMF configuration such as enabling the optional plug-
ins and services, see the IBM publication z/OSMF Configuration Guide.
Assumptions
This document is intended for a first time z/OSMF setup. If z/OSMF is already configured on your system,
you do not need to create a z/OSMF Lite configuration.
This document is designed for use with a single z/OS system, not a z/OS sysplex. If you plan to run z/OSMF
in a sysplex, see z/OSMF Configuration Guide for multi-system considerations.
It is assumed that a basic level of security for z/OSMF is sufficient on the z/OS system. IBM provides a
program, IZUNUSEC, to help you set up basic security for a z/OSMF Lite configuration.
System defaults are used for the z/OSMF environmental settings. Wherever possible, it is recommended that
you use the default values. If necessary, however, you can override the defaults by supplying an IZUPRMxx
member, as described in Appendix A. Creating an IZUPRMxx parmlib member.
It is recommended that you use the following procedures as provided by IBM:
Started procedures IZUSVR1 and IZUANG1
Logon procedure IZUFPROC
Information about installing these procedures is provided in Copying the IBM procedures into JES PROCLIB.

Software Requirements
Setting up z/OSMF Lite requires that you have access to a z/OS V2R2 system or later. Also, your z/OS
system must meet the following minimum software requirements:
Minimum Java level
WebSphere® Liberty profile (z/OSMF V2R3 and later)
System settings
Web browser
Minimum Java level
Java™ must be installed and operational on your z/OS system, at the required minimum level. See the table
that follows for the minimum level and default location. If you installed Java in another location, you must
specify the JAVA_HOME statement in your IZUPRMxx parmlib member, as described in Appendix A.
Creating an IZUPRMxx parmlib member.
 z/OS Minimum level of Java™ Recommended Default location
Version level of Java
IBM® 64-bit SDK for z/OS®, Java
Technology Edition V7.1 (SR3), with IBM® 64-bit SDK
z/OS the PTFs for APAR PI71018 and APAR for z/OS®, Java™
V2R2 PI71019 applied OR IBM® 64-bit SDK Technology /usr/lpp/java/J7.1_64
for z/OS®, Java Technology Edition Edition, V8 SR6
V8, with the PTF for APAR PI72601 (5655-DGH)
applied.
IBM® 64-bit SDK
z/OS IBM® 64-bit SDK for z/OS®, Java™ for z/OS®, Java™
V2R3 Technology Edition, V8 SR4 FP10 Technology /usr/lpp/java/J8.0_64
(5655-DGH) Edition, V8 SR6
(5655-DGH)

WebSphere® Liberty profile (z/OSMF V2R3 and later)

z/OSMF V2R3 uses the Liberty Profile that is supplied with z/OS, rather than its own copy of Liberty. The
WebSphere Liberty profile must be mounted on your z/OS system. The default mount point is:
/usr/lpp/liberty_zos . To determine whether WebSphere® Liberty profile is mounted, check for the
existence of the mount point directory on your z/OS system.
If WebSphere® Liberty profile is mounted at a non-default location, you need to specify the location in the
IZUSVR1 started procedure on the keyword WLPDIR=. For details, see Appendix B. Modifying IZUSVR1
settings.
Note: Whenever you apply PTFs for z/OSMF, you might be prompted to install outstanding WebSphere
Liberty service. It is recommended that you do so to maintain z/OSMF functionality.
System settings
Ensure that the z/OS host system meets the following requirements:
Port 443 (default port) is available for use.
The system host name is unique and maps to the system on which z/OSMF Lite will be configured.
Otherwise, you might encounter errors later in the process. If you encounter errors, see Troubleshooting
problems for the corrective actions to take.
Web browser
For the best results with z/OSMF, use one of the following web browsers on your workstation:
Microsoft Internet Explorer Version 11 or later
Microsoft Edge (Windows 10)
Mozilla Firefox ESR Version 52 or later.
To check your web browser's level, click About in the web browser.

Creating a z/OSMF nucleus on your system

The following system changes are described in this chapter:
Running job IZUNUSEC to create security
Running job IZUMKFS to create the z/OSMF user file system
Copying the IBM procedures into JES PROCLIB
Starting the z/OSMF server
Accessing the z/OSMF Welcome page
Mounting the z/OSMF user file system at IPL time
The following sample jobs that you might use are included in the package and available for download:
IZUAUTH
IZUICSEC
IZUNUSEC_V2R2
IZUNUSEC_V2R3
IZUPRM00
IZURFSEC
IZUTSSEC
IZUWFSEC
Download sample jobs
Check out the video for a demo of the process:

Running job IZUNUSEC to create security

The security job IZUNUSEC contains a minimal set of RACF® commands for creating security profiles for the
z/OSMF nucleus. The profiles are used to protect the resources that are used by the z/OSMF server, and to
grant users access to the z/OSMF core functions. IZUNUSEC is a simplified version of the sample job
IZUSEC, which is intended for a more complete installation of z/OSMF.
Note: If your implementation uses an external security manager other than RACF (for example, Top Secret or
ACF2), provide equivalent commands for your environment. For more information, see the following product
documentation:
Configure z/OS Management Facility for Top Secret
Configure z/OS Management Facility for ACF2
Before you begin
In most cases, you can run the IZUNUSEC security job without modification. To verify that the job is okay to
run as is, ask your security administrator to review the job and modify it as necessary for your security
environment. If security is not a concern for the host system, you can run the job without modification.
Procedure
. If you run z/OS V2R2 or V2R3, download job IZUNUSEC in the sample jobs package and upload this job
to z/OS. If you run z/OS V2R4, locate job IZUNUSEC at SYS1.SAMPLIB.
. Review and edit the job, if necessary.
. Submit IZUNUSEC as a batch job on your z/OS system.
. Connect your user ID to IZUADMIN group.
i. Download job IZUAUTH in the sample jobs package and customize it.
ii. Replace the 'userid' with your z/OSMF user ID.
iii. Submit the job on your z/OS system.
Results
Ensure the IZUNUSEC job completes with return code 0000 .
To verify, check the results of the job execution in the job log. For example, you can use SDSF to examine the
job log:
. In the SDSF primary option menu, select Option ST.
. On the SDSF Status Display, enter S next to the job that you submitted.
. Check the return code of the job. The job succeeds if '0000' is returned.
Common errors
Review the following messages and the corresponding resolutions as needed:
Symptom Cause Resolution
Message IKJ56702I: The job is
INVALID data is submitted more You can ignore this message.
issued than once.
Job fails with an Your user ID lacks Contact your security admin to run IZUNUSEC. If you are
authorization error. superuser using RACF®, select a user ID with SPECIAL attribute
authority. which can issue all RACF® commands.
 Symptom Cause Resolution
Your installation
Job fails with an uses the RACF See Troubleshooting problems.
authorization error. PROTECT-ALL
option.
ADDGROUP and The automatic GID
ADDUSER and UID Define SHARED.IDS and BPX.NEXT.USER profiles to
commands are not assignment is enable the use of AUTOUID and AUTOGID.
executed. required.

Running job IZUMKFS to create the z/OSMF user file system

The job IZUMKFS initializes the z/OSMF user file system, which contains configuration settings and
persistence information for z/OSMF.
The job mounts the file system. On a z/OS V2R3 system with the PTF for APAR PI92211 installed, the job
uses mount point /global/zosmf . Otherwise, for an earlier system, the job mounts the file system at
mount point /var/zosmf .
Before you begin
To perform this step, you need a user ID with "superuser" authority on the z/OS host system. For more
information about how to define a user with superuser authority, see the publication z/OS UNIX System
Services.
Procedure
. In the system library SYS1.SAMPLIB , locate job IZUMKFS.
. Copy the job.
. Review and edit the job:
Modify the job information so that the job can run on your system.
You must specify a volume serial (VOLSER) to be used for allocating a data set for the z/OSMF data
directory.
 . Submit IZUMKFS as a batch job on your z/OS system.
Results
The z/OSMF file system is allocated, formatted, and mounted, and the necessary directories are created.
To verify if the file system is allocated, formatted, locate the following messages in IZUMKFS job output.
Sample output:

Common errors
Review the following messages and the corresponding resolutions as needed
Symptom Cause Resolution

Job fails with Your user ID lacks For more information about how to define a user with
FSM error. superuser superuser authority, see the publication z/OS UNIX System
authority. Services.
Job fails with an Job statement
authorization errors. See Troubleshooting problems.
error.

Copying the IBM procedures into JES PROCLIB

Copy the z/OSMF started procedures and logon procedure from SYS1.PROCLIB into your JES
concatenation. Use $D PROCLIB command to display your JES2 PROCLIB definitions.
Before you begin
Locate the IBM procedures. IBM supplies procedures for z/OSMF in your z/OS order:
 ServerPac and CustomPac orders: IBM supplies the z/OSMF procedures in the SMP/E managed proclib
data set. In ServerPac and SystemPac, the default name for the data set is SYS1.IBM.PROCLIB.
CBPDO orders: For a CBPDO order, the SMP/E-managed proclib data set is named as SYS1.PROCLIB.
Application Development CD.
Procedure
Use ISPF option 3.3 or 3.4 to copy the procedures from SYS1.PROCLIB into your JES concatenation.
IZUSVR1
IZUANG1
IZUFPROC
Results
The procedures now reside in your JES PROCLIB.
Common errors
Review the following messages and the corresponding resolutions as needed
Symptom Cause Resolution
Not authorized to Your user ID doesn't have the Contact your security administrator.
copy into PROCLIB. permission to modify PROCLIB.
Abend code B37 or The data set runs out of space. Use IEBCOPY utility to compress
E37. PROCLIB dataset before you copy it.

Starting the z/OSMF server

z/OSMF processing is managed through the z/OSMF server, which runs as the started tasks IZUANG1 and
IZUSVR1. z/OSMF is started with the START command.
Before you begin
Ensure that you have access to the operations console and can enter the START command.
Procedure
In the operations console, enter the START commands sequentially:
Note: The z/OSMF angel (IZUANG1) must be started before the z/OSMF server (IZUSVR1).
You must enter these commands manually at subsequent IPLs. If necessary, you can stop z/OSMF
processing by entering the STOP command for each of the started tasks IZUANG1 and IZUSVR1.
Note: z/OSMF offers an autostart function, which you can configure to have the z/OSMF server started
automatically. For more information about the autostart capability, see z/OSMF Configuration Guide.
Results
When the z/OSMF server is initialized, you can see the following messages displayed in the operations
console:
Accessing the z/OSMF Welcome page
At the end of the z/OSMF configuration process, you can verify the results of your work by opening a web
browser to the Welcome page.
Before you begin
To find the URL of the Welcome page, look for message IZUG349I in the z/OSMF server job log.

Procedure
. Open a web browser to the z/OSMF Welcome page. The URL for the Welcome page has the following
format: https://hostname:port/zosmf/
Where:
hostname is the host name or IP address of the system in which z/OSMF is installed.
port is the secure port for the z/OSMF configuration. If you specified a secure port for SSL
encrypted traffic during the configuration process through parmlib statement HTTP_SSL_PORT,
 port is required to log in. Otherwise, it is assumed that you use the default port 443.
. In the z/OS USER ID field on the Welcome page, enter the z/OS user ID that you use to configure
z/OSMF.
. In the z/OS PASSWORD field, enter the password or pass phrase that is associated with the z/OS user
ID.
. Select the style of UI for z/OSMF. To use the desktop interface, select this option. Otherwise, leave this
option unselected to use the tree view UI.
. Click Log In.
Results
If the user ID and password or pass phrase are valid, you are authenticated to z/OSMF. The Welcome page
of IBM z/OS Management Facility tab opens in the main area. At the top right of the screen, Welcome
<your_user_ID> is displayed. In the UI, only the options you are allowed to use are displayed.

You have successfully configured the z/OSMF nucleus.

Common errors
The following errors might occur during this step:
Symptom Cause Resolution
The SSL handshake was
z/OSMF welcome page does not load not successful. This See Certificate error in the
in your web browser. problem can be related to Mozilla Firefox browser.
the browser certificate.
To log into z/OSMF, enter a valid z/OS The user ID is not
user ID and password. Your account connected to the Connect your user ID to the
might be locked after too many IZUADMIN group. IZUADMIN group.
incorrect log-in attempts.
 Symptom Cause Resolution
To log into z/OSMF, enter a valid z/OS Log on to TSO using your z/OS
user ID and password. Your account The password is expired. User ID and password, you will
might be locked after too many be asked to change your
incorrect log-in attempts. password if it's expired.

Mounting the z/OSMF user file system at IPL time

Previously, in Running job IZUMKFS to create the z/OSMF user file system, you ran job IZUMKFS to create
and mount the z/OSMF user file system. Now you should ensure that the z/OSMF user file system is
mounted automatically for subsequent IPLs. To do so, update the BPXPRMxx parmlib member on your z/OS
system.
Before you begin
By default, the z/OSMF file system uses the name IZU.SIZUUSRD, and is mounted in read/write mode. It is
recommended that this file system is mounted automatically at IPL time.
If you do not know which BPXPRMxx member is active, follow these steps to find out:
. In the operations console, enter the following command to see which parmlib members are included in
the parmlib concatenation on your system:
D PARMLIB

. Make a note of the BPXPRMxx member suffixes that you see.

. To determine which BPXPRMxx member takes precedence, enter the following command:
D OMVS

The output of this command should be similar to the following:

In this example, the member BPXPRMST takes precedence. If BPXPRMST is not present in the
concatenation, member BPXPRM3T is used.
Procedure
Add a MOUNT command for the z/OSMF user file system to your currently active BPXPRMxx parmlib
member. For example:
On a z/OS V2R3 system with the PTF for APAR PI92211 installed:
On a z/OS V2R2 or V2R3 system without PTF for APAR PI92211 installed:
Results
The BPXPRMxx member is updated. At the next system IPL, the following message is issued to indicate that
the z/OSMF file system is mounted automatically.

Adding the required REST services

You must enable a set of z/OSMF REST services for the Zowe framework.
The following system changes are described in this topic:
Enabling the z/OSMF JOB REST services
Enabling the TSO REST services
Enabling the z/OSMF data set and file REST services
Enabling the z/OSMF Workflow REST services and Workflows task UI
Enabling the z/OSMF JOB REST services
The Zowe framework requires that you enable the z/OSMF JOB REST services, as described in this topic.
Procedure
None
Results
To verify if the z/OSMF JOB REST services are enabled, open a web browser to our z/OS system (host name
and port) and add the following REST call to the URL:
GET /zosmf/restjobs/jobs

The result is a list of the jobs that are owned by your user ID. For more information about the z/OSMF JOB
REST services, see z/OSMF Programming Guide.
Common errors
Review the following messages and the corresponding resolutions as needed:
Symptom 1
401 Unauthorized
Cause
The user ID is not connected to IZUADMIN or IZUUSER.
Resolution
Connect your user ID to IZUADMIN or IZUUSER.
Symptom 2
HTTP/1.1 500 Internal Server Error {"rc":16,"reason":-1,"stack":"JesException: CATEGORY_CIM rc=16
reason=-1 cause=com.ibm.zoszmf.util.eis.EisConnectionException: IZUG911I: Connection to
\"http:\/\/null:5988\" cannot be established, or was lost and cannot be re-established using protocol
\"CIM\"......Caused by: WBEMException: CIM_ERR_FAILED (JNI Exception type
CannotConnectException:\nCannot connect to local CIM server. Connection failed.)
Cause
For JES2, you may have performed one of the following "Modify" operations: Hold a job, Release a job,
Change the job class, Cancel a job, Delete a job (Cancel a job and purge its output), or you are running JES3
without configuring CIM Server.
Resolution
If you are running JES2, you can use synchronous support for job modify operations which does not
required CIM. If you are running JES3, follow the CIM setup instructions to configure CIM on your system.
Enabling the TSO REST services
The Zowe framework requires that you enable the TSO REST services, as described in this topic.
Before you begin
Ensure that the common event adapter component (CEA) of z/OS is running in full function mode.
 . To check if the CEA address space is active, enter the following command:
D A,CEA

. If not, start CEA in full function mode. For detailed instructions, see System prerequisites for the CEA
TSO/E address space services.
. To verify that CEA is running in full function mode, enter the following command:
F CEA,D

The output should look like the following:

Procedure
. If you run z/OS V2R2 and V2R3, download job IZUTSSEC in the sample jobs package and upload this
Job to z/OS. If you run z/OS V2R4, locate job IZUTSSEC at SYS1.SAMPLIB .
. Review and edit job IZUTSSEC before you submit. You can review the IZUTSSEC section below for more
details.
. Submit IZUTSSEC as a batch job on your z/OS system.
IZUTSSEC
IBM provides a set of jobs in SYS1.SAMPLIB with sample RACF commands to help with your z/OSMF
configuration and its prerequisites. The IZUTSSEC job represents the authorizations that are needed for the
z/OSMF TSO/E address space service. Your security administrator can edit and run the job. Generally, your
z/OSMF user ID requires the same authorizations for using the TSO/E address space services as when you
perform these operations through a TSO/E session on the z/OS system. For example, to start an application
in a TSO/E address space requires that your user ID be authorized to operate that application. In addition, to
use TSO/E address space services, you must have:
READ access to the account resource in class ACCTNUM, where account is the value specified in the
COMMON_TSO ACCT option in parmlib.
READ access to the CEA.CEATSO.TSOREQUEST resource in class SERVAUTH.
READ access to the proc resource in class TSOPROC, where proc is the value specified with the
COMMON_TSO PROC option in parmlib.
READ access to the <SAF_PREFIX>.*.izuUsers profile in the EJBROLE class. Or, at a minimum, READ
access to the <SAF_PREFIX>.IzuManagementFacilityTsoServices.izuUsers resource name in the
EJBROLE class. You must also ensure that the z/OSMF started task user ID, which is IZUSVR by default,
 has READ access to the CEA.CEATSO.TSOREQUEST resource in class SERVAUTH. To create a TSO/E
address space on a remote system, you require the following authorizations:
You must be authorized to the SAF resource profile that controls the ability to send data to the remote
system (systemname), as indicated: CEA.CEATSO.FLOW.systemname
To flow data between different systems in the sysplex, you must be authorized to do so by your external
security manager, such as a RACF database with sysplex-wide scope. For example, to flow data
between System A and System B, you must be permitted to the following resource profiles:
CEA.CEATSO.FLOW.SYSTEMA
CEA.CEATSO.FLOW.SYSTEMB
Results
The IZUTSSEC job should complete with return code 0000.
Enabling the z/OSMF data set and file REST services
The Zowe framework requires that you enable the z/OSMF data set and file REST services.
Before you begin
. Ensure that the message queue size is set to a large enough value. It is recommended that you specify
an IPCMSGQBYTES value of at least 20971520 (20M) in BPXPRMxx.
Issue command D OMVS,O to see the current value of IPCMSGQBYTES, if it is not large enough, use
the SETOMVS command to set a large value. To set this value dynamically, you can enter the following
operator command:
SETOMVS IPCMSGQBYTES=20971520

. Ensure that the TSO REST services are enabled.

. Ensure that IZUFPROC is in your JES concatenation.
. Ensure that your user ID has a TSO segment defined. To do so, enter the following command from
TSO/E command prompt:
LU userid TSO

Where userid is your z/OS user ID.

The output from this command must include the section called TSO information, as shown in the following
example:
Procedure
. If you run z/OS V2R2 and V2R3, download job IZURFSEC in the sample jobs package and upload it to
z/OS. If you run z/OS V2R4, locate job IZURFSEC at SYS1.SAMPLIB .
. Copy the job.
. Examine the contents of the job.
. Modify the contents as needed so that the job will run on your system.
. From the TSO/E command line, run the IZURFSEC job.
Results
Ensure that the IZURFSEC job completes with return code 0000 .
To verify if this setup is complete, try issuing a REST service. See the example in List data sets in the z/OSMF
programming guide.
Common errors
Review the following messages and the corresponding resolutions as needed:
Symptom Cause Resolution

REST API doesn't return expected The Ensure that the message queue size is set to a
data with rc=12, rsn=3, message: message large enough value. It is recommended that you
message queue size "SIZE" is less queue size specify an IPCMSGQBYTES value of at least
than minimum: 20M for CEA is 20971520 (20M) in BPXPRMx.
too small.

Enabling the z/OSMF Workflow REST services and Workflows task UI

The Zowe framework requires that you enable the z/OSMF Workflow REST services and Workflows task UI.
Before you begin
. Ensure that the JOB REST services are enabled.
 . Ensure that the TSO REST services are enabled.
. Ensure that the dataset and file REST services are enabled.
Procedure
. If you run z/OS V2R2 and V2R3, download job IZUWFSEC in the sample jobs package and upload this
job to z/OS. If you run z/OS V2R4, locate job IZUWFSEC at SYS1.SAMPLIB .
. Copy the job.
. Examine the contents of the job.
. Modify the contents as needed so that the job will run on your system.
. From the TSO/E command line, run the IZUWFSEC job.
Results
Ensure the IZUWFSEC job completes with return code 0000 .
To verify, log on to z/OSMF (or refresh it) and verify that the Workflows task appears in the z/OSMF UI.
At this point, you have completed the setup of z/OSMF Lite.
Optionally, you can add more users to z/OSMF, as described in Appendix C. Adding more users to z/OSMF.

Troubleshooting problems
This section provides tips and techniques for troubleshooting problems you might encounter when creating
a z/OSMF Lite configuration. For other types of problems that might occur, see z/OSMF Configuration Guide.
Common problems and scenarios
This section discusses troubleshooting topics, procedures, and tools for recovering from a set of known
issues.
System setup requirements not met
This document assumes that the following is true of the z/OS host system:
Port 443 is available for use. To check this, issue either TSO command NETSTAT SOCKET or TSO
command NETSTAT BYTE to determine if the port is being used.
 The system host name is unique and maps to the system on which z/OSMF Lite is being installed. To
retrieve this value, enter either "hostname" z/OS UNIX command or TSO command "HOMETEST". If
your system uses another method of assigning the system name, such as a multi-home stack, dynamic
VIPA, or System Director, see z/OSMF Configuration Guide.
The global mount point exists. On a z/OS 2.3 system, the system includes this directory by default. On a
z/OS 2.2 system, you must create the global directory at the following location: /global/zosmf/ .
If you find that a different value is used on your z/OS system, you can edit the IZUPRMxx parmlib member to
specify the correct setting. For details, see Appendix A. Creating an IZUPRMxx parmlib member.
Tools and techniques for troubleshooting
For information about working with z/OSMF log files, see z/OSMF Configuration Guide.
Common messages
If you see above error messages, check if your IZUANG0 procedure is up to date.
For descriptions of all the z/OSMF messages, see z/OSMF messages in IBM Knowledge Center.

Appendix A. Creating an IZUPRMxx parmlib member

If z/OSMF requires customization, you can modify the applicable settings by using the IZUPRMxx parmlib
member. To see a sample member, locate the IZUPRM00 member in the SYS1.SAMPLIB data set. IZUPRM00
contains settings that match the z/OSMF defaults.
Using IZUPRM00 as a model, you can create a customized IZUPRMxx parmlib member for your environment
and copy it to SYS1.PARMLIB to override the defaults.
The following IZUPRMxx settings are required for the z/OSMF nucleus:
HOSTNAME
HTTP_SSL_PORT
JAVA_HOME.
The following setting is needed for the TSO/E REST services:
 COMMON_TSO ACCT(IZUACCT) REGION(50000) PROC(IZUFPROC)
Descriptions of these settings are provided in the table below. For complete details about the IZUPRMxx
settings and the proper syntax for updating the member, see z/OSMF Configuration Guide.
If you change values in the IZUPRMxx member, you might need to customize the started procedure
IZUSVR1, accordingly. For details, see Appendix B. Modifying IZUSVR1 settings.
To create an IZUPRMxx parmlib member, follow these steps:
. Copy the sample parmlib member into the desired parmlib data set with the desired suffix.
. Update the parmlib member as needed.
. Specify the IZUPRMxx parmlib member or members that you want the system to use on the IZU
parameter of IEASYSxx. Or, code a value for IZUPRM= in the IZUSVR1 started procedure. If you specify
both IZU= in IEASYSxx and IZUPARM= in IZUSVR1, the system uses the IZUPRM= value you specify in
the started procedure.
Setting Purpose Rules Default
Specifies the host name, as defined by
DNS, where the z/OSMF server is
located. To use the local host name,
enter asterisk (*), which is equivalent Must be a
to \@HOSTNAME from previous valid TCP/IP
HOSTNAME(hostname) releases. If you plan to use z/OSMF in a HOSTNAME Default: *
multisystem sysplex, IBM recommends or an asterisk
using a dynamic virtual IP address (*).
(DVIPA) that resolves to the correct IP
address if the z/OSMF server is moved
to a different system.
 Setting Purpose Rules Default
Identifies the port number that is
associated with the z/OSMF server.
This port is used for SSL encrypted
traffic from your z/OSMF configuration. Must be a
The default value, 443, follows the valid TCP/IP
Internet Engineering Task Force (IETF) port number.
HTTP_SSL_PORT(nnn) standard. Note: By default, the Value range: Default: 443
z/OSMF server uses the SSL protocol 1 - 65535
SSL_TLSv2 for secure TCP/IP (up to 5
communications. As a result, the digits)
server can accept incoming
connections that use SSL V3.0 and the
TLS 1.0, 1.1 and 1.2 protocols.
The valid
COMMON_TSO ranges for
ACCT(account- Specifies values for the TSO/E logon each value Default: 443
number) procedure that is used internally for are ACCT(IZUACCT)
REGION(region-size) various z/OSMF activities and by the described in REGION(50000)
PROC(proc-name) Workflows task. z/OSMF PROC(IZUFPROC)
Configuration
Guide.
z/OSMF data directory path. By
default, the z/OSMF data directory is Must be a
located in /global/zosmf . If you valid z/OS Default:
USER_DIR=filepath want to use a different path for the UNIX path
z/OSMF data directory, specify that name.
/global/zosmf/

value here, for example:

USER_DIR= /the/new/config/dir .

Appendix B. Modifying IZUSVR1 settings

You might need to customize the started procedure IZUSVR1 for z/OSMF Lite.
To modify the IZUSVR1 settings, follow these steps:
. Make a copy
. Apply your changes
. Store your copy in PROCLIB.
Setting Purpose Rules Default
The
directory
path
must: Be
a valid
z/OS
UNIX
path
name Be
a full or
WLPDIR='directory- WebSphere Liberty server code path. absolute Default:
path' path /usr/lpp/zosmf/liber
name Be
enclosed
in
quotation
marks
Begin
with a
forward
slash
('/').
 Setting Purpose Rules Default
z/OSMF data directory path. By Must be
default, the z/OSMF data directory is a valid
located in /global/zosmf. If you want to z/OS
USER_DIR=filepath use a different path for the z/OSMF UNIX Default: /global/zosmf/
data directory, specify that value here, path
for example: name.
USER_DIR= /the/new/config/dir .

Appendix C. Adding more users to z/OSMF

Your security administrator can authorize more users to z/OSMF. Simply connect the required user IDs to the
z/OSMF administrator group (IZUADMIN). This group is permitted to a default set of z/OSMF resources
(tasks and services). For the specific group permissions, see Appendix A in z/OSMF Configuration Guide.
You can create more user groups as needed, for example, one group per z/OSMF task.
Before you Begin
Collect the z/OS user IDs that you want to add.
Procedure
. On an RACF system, enter the CONNECT command for the user IDs to be granted authorization to
z/OSMF resources:
CONNECT userid GROUP(IZUADMIN)

Results
The user IDs can now access z/OSMF.
Installing Zowe runtime from a convenience
Version: v2.0.x LTS

build
You install the Zowe™ convenience build by obtaining a PAX file and using this to create the Zowe runtime
environment.

Introduction
The Zowe installation file for Zowe z/OS components is distributed as a PAX file that contains the runtimes
and the scripts to install and launch the z/OS runtime. You must obtain the PAX file and transfer it to z/OS
first. Then, to install, configure and start Zowe, you use the zwe command. This command defines help
messages, logging options, and more. For details about how to use this command, see the ZWE Server
Command Reference.
The configuration data that is read by the zwe command are stored in a YAML configuration file named
zowe.yaml . You modify the zowe.yaml file based on your environment.

Complete the following steps to install the Zowe runtime.

Step 1: Obtain the convenience build

To download the PAX file, open your web browser on the Zowe Download website, navigate to Zowe V2
Preview -> Convenience build section, and select the button to download the v2 convenience build.

Step 2: Transfer the convenience build to USS and expand

it
After you download the PAX file, you can transfer it to z/OS and expand its contents.
. Open a terminal in Mac OS/Linux, or command prompt in Windows OS, and navigate to the directory
where you downloaded the Zowe PAX file.
. Connect to z/OS using SFTP. Issue the following command:
 If SFTP is not available or if you prefer to use FTP, you can issue the following command instead:
. Navigate to the target directory that you want to transfer the Zowe PAX file into on z/OS.
Note: After you connect to z/OS and enter your password, you enter the UNIX file system. The following
commands are useful:
To see what directory you are in, type pwd .
To switch directory, type cd .
To list the contents of a directory, type ls .
To create a directory, type mkdir .
. When you are in the directory you want to transfer the Zowe PAX file into, issue the following command:
Where zowe-V.v.p is a variable that indicates the name of the PAX file you downloaded.
Note: When your terminal is connected to z/OS through FTP or SFTP, you can prepend commands with
l to have them issued against your desktop. To list the contents of a directory on your desktop, type
lls where ls lists contents of a directory on z/OS.

After the PAX file has sucessfully transferred, exit your sftp or ftp session.
. Open a USS shell to expand the PAX file. This can either be an ssh terminal, OMVS, iShell, or any other
z/OS unix system services command environment.
. Expand the PAX file by issuing the following command in the USS shell.
Where zowe-V.v.p is a variable that indicates the name of the PAX file you downloaded. When extracting
the Zowe convenience build, you must always include the -ppx argument that preserves extended
attributes.
This will expand to a file structure similar to the following one.
This is the Zowe runtime directory and is referred to as <RUNTIME_DIR> throughout this
documentation.
Note: Zowe version 1 had a script zowe-install.sh that created a separate Zowe runtime directory
from the expanded contents of the Zowe PAX file. Zowe v2 no longer has this step. In Zowe v2, the
contents of the expanded Zowe PAX file are the Zowe runtime directory.
Step 3: (Optional) Add the zwe command to your PATH
The zwe command is provided in the <RUNTIME_DIR>/bin directory. You can optionally add this Zowe
bin directory to your PATH environment variable so you can execute the zwe command without having to
fully qualify its location. To update your PATH , run the following command:
<RUNTIME_DIR> should be replaced with your real Zowe runtime directory path. This will update the
PATH for the current shell. To make this update persistent, you can add the line to your ~/.profile file,
or the ~/.bashProfile file if you are using a bash shell. To make this update system wide, you can
update the /etc/.profile file. Once the PATH is updated, you can execute the zwe command from
any USS directory. For the remainder of the documentation when zwe command is referenced, it is
assumed that it has been added to your PATH .
The zwe command has built in help that can be retrieved with the -h suffix. For example, type zwe -h
to display all of the supported commands. These are broken down into a number of sub-commands.

Step 4: Copy the zowe.yaml configuration file to preferred

location
Copy the template file <RUNTIME_DIR>/example-zowe.yaml file to a new location, such as
/var/lpp/zowe/zowe.yaml or your home directory ~/.zowe.yaml . This will become your
configuration file that contains data used by the zwe command at a number of parts of the lifecycle of
configuring and starting Zowe. You will need to modify the zowe.yaml file based on your environment.
When you execute the zwe command, the -c argument is used to pass the location of a zowe.yaml
file.
TIP
To avoid passing --config or -c to every zwe commands, you can define
ZWE_CLI_PARAMETER_CONFIG environment variable points to location of zowe.yaml.

For example, after defining

, you can simply type zwe install instead of full command zwe install -c
/path/to/my/zowe.yaml .
Step 5: Install the MVS data sets
After you extract the Zowe convenience build, you can run the zwe install command to install MVS
data sets.
About the MVS data sets
Zowe includes a number of files that are stored in the following three data sets. See the following table for
the storage requirements.
No. No.
Library Member Type Target Type Org RECFM LRECL of of
DDNAME Volume 3390 DIR
Trks Blks
SZWESAMP Samples ANY U PDSE FB 80 15 5

SZWEAUTH Zowe APF Load ANY

Modules U PDSE U 0 15 N/A

SZWEEXEC CLIST
utilities
copy ANY U PDSE FB 80 15 5

The SZWESAMP data set contains the following members.

Member Purpose
name
ZWESECUR JCL member to configure z/OS user IDs and permissions required to run Zowe
ZWENOSEC JCL member to undo the configuration steps performed in ZWESECUR and revert z/OS
environment changes.
ZWEKRING JCL member to configure a z/OS keyring containing the Zowe certificate
ZWENOKYR JCL member to undo the configuration steps performed in ZWEKRING
 Member Purpose
name
ZWESLSTC JCL to start Zowe
ZWEXMSTC JCL to start the Zowe cross memory server
ZWESIP00 Parmlib member for the cross memory server
ZWESASTC Started task JCL for the cross memory Auxiliary server
ZWESIPRG Console commands to APF authorize the cross memory server load library
ZWESISCH PPT entries required by Cross memory server and its Auxiliary address spaces to run in
Key(4)
ZWECSVSM JCL Member to create the VSAM data set for the caching service
The SZWEAUTH data set is a load library containing the following members.
Member Purpose
name

ZWELNCH The Zowe launcher that controls the startup, restart and shutdown of Zowe's address
spaces
ZWESIS01 Load module for the cross memory server
ZWESAUX Load module for the cross memory server's auxiliary address space
The SZWEEXEC data set contains few utilities used by Zowe.
Procedure
The high level qualifer (or HLQ) for these data sets is specified in the zowe.yaml section below. Ensure
that you update the zowe.setup.dataset.prefix value to match your system.
To create and install the MVS data sets, use the command zwe install .
. In a USS shell, execute the command zwe install -c /path/to/zowe.yaml . This creates the
three data sets and copy across their content.
. If the data sets already exist, specify --allow-overwritten .
. To see the full list of parameters, execute the command zwe install -h .
A sample run of the command is shown below using default values.

Next steps
You successfully installed Zowe from the convenience build! However, before you start Zowe, you must
complete several required configurations. Next, go to Initialize the z/OS system and permissions to initialize
your z/OS system for Zowe first.
Installing Zowe SMP/E
Version: v2.0.x LTS

Contents
Introduction
Zowe description
Zowe FMIDs
Program materials
Basic machine-readable material
Program publications
Program source materials
Publications useful during installation
Program support
Statement of support procedures
Program and service level information
Program level information
Service level information
Installation requirements and considerations
Driving system requirements
Driving system machine requirements
Driving system programming requirements
Target system requirements
Target system machine requirements
Target system programming requirements
DASD storage requirements
FMIDs deleted
Installation instructions
SMP/E considerations for installing Zowe
SMP/E options subentry values
Overview of the installation steps
Download the Zowe SMP/E package
Allocate file system to hold the download package
Upload the download package to the host
 Extract and expand the compressed SMPMCS and RELFILEs
GIMUNZIP
Sample installation jobs
Create SMP/E environment (optional)
Perform SMP/E RECEIVE
Allocate SMP/E Target and Distributions Libraries
Allocate, create and mount ZSF Files (Optional)
Allocate z/OS UNIX Paths
Create DDDEF Entries
Perform SMP/E APPLY
Perform SMP/E ACCEPT
Run REPORT CROSSZONE
Cleaning up obsolete data sets, paths, and DDDEFs
Activating Zowe
File system execution
Zowe customization

Introduction
This program directory is intended for system programmers who are responsible for program installation and
maintenance. It contains information about the material and procedures associated with the installation of
Zowe Open Source Project (Base). This publication refers to Zowe Open Source Project (Base) as Zowe.
The Program Directory contains the following sections:
Program Materials identifies the basic program materials and documentation for Zowe.
Program Support describes the support available for Zowe.
Program and Service Level Information lists the APARs (program level) and PTFs (service level) that
have been incorporated into Zowe.
Installation Requirements and Considerations identifies the resources and considerations that are
required for installing and using Zowe.
Installation Instructions provides detailed installation instructions for Zowe. It also describes the
procedures for activating the functions of Zowe, or refers to appropriate publications.
Zowe description
Zowe™ is an open source project created to host technologies that benefit the Z platform. It is a sub-project
of Open Mainframe Project which is part of the Linux Foundation. More information about Zowe is available
at https://zowe.org.
Zowe FMIDs
Zowe consists of the following FMIDs:
AZWE002

Program materials
Basic Machine-Readable Materials are materials that are supplied under the base license and are required
for the use of the product.
Basic machine-readable material
The distribution medium for this program is via downloadable files. This program is in SMP/E RELFILE format
and is installed using SMP/E. See Installation instructions for more information about how to install the
program.
Program source materials
No program source materials or viewable program listings are provided for Zowe in the SMP/E installation
package. However, program source materials can be downloaded from the Zowe GitHub repositories at
https://github.com/zowe/.
Publications useful during installation
Publications listed below are helpful during the installation of Zowe.
Publication Title Form Number
IBM SMP/E for z/OS User's Guide SA23-2277
IBM SMP/E for z/OS Commands SA23-2275
 Publication Title Form Number
IBM SMP/E for z/OS Reference SA23-2276
IBM SMP/E for z/OS Messages, Codes, and Diagnosis GA32-0883
These and other publications can be obtained from https://www.ibm.com/shop/publications/order.

Program support
This section describes the support available for Zowe.
Because this is an alpha release of the Zowe FMID package for early testing and adoption, no formal support
is offered. Support is available through the Zowe community. See Community Engagement for details. Slack
is the preferred interaction channel.
Additional support may be available through other entities outside of the Open Mainframe Project and Linux
Foundation which offers no warranty and provides the package under the terms of the EPL v2.0 license.
Statement of support procedures
Report any problems which you feel might be an error in the product materials to the Zowe community via
the Zowe GitHub community repo at https://github.com/zowe/community/issues/new/choose. You may be
asked to gather and submit additional diagnostics to assist the Zowe Community for analysis and resolution.

Program and service level information

This section identifies the program and relevant service levels of Zowe. The program level refers to the APAR
fixes that have been incorporated into the program. The service level refers to the PTFs that have been
incorporated into the program.
Program level information
All issues of previous releases of Zowe that were resolved before August 2019 have been incorporated into
this packaging of Zowe.
Service level information
The Zowe SMP/E package is a distribution of Zowe version 2.0.0 with an FMID of AZWE002.
Subsequent releases of the Zowe z/OS components are delivered as rollup PTFs on zowe.org.

Installation requirements and considerations

The following sections identify the system requirements for installing and activating Zowe. The following
terminology is used:
Driving System: the system on which SMP/E is executed to install the program.
Target system: the system on which the program is configured and run.
Use separate driving and target systems in the following situations:
When you install a new level of a product that is already installed, the new level of the product will
replace the old one. By installing the new level onto a separate target system, you can test the new level
and keep the old one in production at the same time.
When you install a product that shares libraries or load modules with other products, the installation can
disrupt the other products. By installing the product onto a separate target system, you can assess
these impacts without disrupting your production system.
Driving system requirements
This section describes the environment of the driving system required to install Zowe.
Driving system machine requirements
The driving system can be run in any hardware environment that supports the required software.
Driving system programming requirements
Program Product Minimum Minimum Service Level will Included in the
Number Name VRM satisfy these APARs shipped product?

5650-ZOS z/OS V2.2.0 or N/A No

later
Notes:
 SMP/E is a requirement for Installation and is an element of z/OS but can also be ordered as a separate
product, 5655-G44, minimally V03.06.00.
Installation might require migration to a new z/OS release to be service supported. See https://www-
01.ibm.com/software/support/lifecycle/index_z.html.
Zowe is installed into a file system, either HFS or zFS. Before installing Zowe, you must ensure that the target
system file system data sets are available for processing on the driving system. OMVS must be active on the
driving system and the target system file data sets must be mounted on the driving system.
If you plan to install Zowe in a zFS file system, this requires that zFS be active on the driving system.
Information on activating and using zFS can be found in z/OS Distributed File Service zSeries File System
Administration (SC24-5989).
Target system requirements
This section describes the environment of the target system required to install and use Zowe.
Zowe installs in the z/OS (Z038) SREL.
Target system machine requirements
The target system can run in any hardware environment that supports the required software.
Target system programming requirements
Installation requisites
Installation requisites identify products that are required and must be present on the system or products that
are not required but should be present on the system for the successful installation of Zowe.
Mandatory installation requisites identify products that are required on the system for the successful
installation of Zowe. These products are specified as PREs or REQs.
Zowe has no mandatory installation requisites.
Conditional installation requisites identify products that are not required for successful installation of Zowe
but can resolve such things as certain warning messages at installation time. These products are specified
as IF REQs.
Zowe has no conditional installation requisites.
Operational requisites
Operational requisites are products that are required and must be present on the system, or, products that
are not required but should be present on the system for Zowe to operate all or part of its functions.
Mandatory operational requisites identify products that are required for this product to operate its basic
functions. The following table lists the target system mandatory operational requisites for Zowe.
Program Number Product Name and Minimum VRM/Service Level
5650-ZOS IBM z/OS Management Facility V2.2.0 or higher
5655-SDK IBM SDK for Node.js - z/OS V12 or higher
5655-DGH IBM 64-bit SDK for z/OS Java Technology Edition V8.0.0
Conditional operational requisites identify products that are not required for Zowe to operate its basic
functions but are required at run time for Zowe to operate specific functions. These products are specified
as IF REQs. Zowe has no conditional operational requisites.
Toleration/coexistence requisites
Toleration/coexistence requisites identify products that must be present on sharing systems. These systems
can be other systems in a multi-system environment (not necessarily Parallel SysplexTM), a shared DASD
environment (such as test and production), or systems that reuse the same DASD environment at different
time intervals.
Zowe has no toleration/coexistence requisites.
Incompatibility (negative) requisites
Negative requisites identify products that must not be installed on the same system as Zowe.
Zowe has no negative requisites.
DASD storage requirements
Zowe libraries can reside on all supported DASD types.
Total DASD space required by Zowe
 Library Total Space Required in Description
Type 3390 Trks
Target 45 Tracks /
Distribution 12045 Tracks /
File 21000 Tracks /
System(s)
Web 38666 Tracks These are temporary data sets, which can be removed
Download after the SMP/E install.
Notes:
. For non-RECFM U data sets, we recommend using system-determined block sizes for efficient DASD
utilization. For RECFM U data sets, we recommend using a block size of 32760, which is most efficient
from the performance and DASD utilization perspective.
. Abbreviations used for data set types are shown as follows.
U - Unique data set, allocated by this product and used by only this product. This table provides all
the required information to determine the correct storage for this data set. You do not need to refer
to other tables or program directories for the data set size.
S - Shared data set, allocated by this product and used by this product and other products. To
determine the correct storage needed for this data set, add the storage size given in this table to
those given in other tables (perhaps in other program directories). If the data set already exists, it
must have enough free space to accommodate the storage size given in this table.
E - Existing shared data set, used by this product and other products. This data set is not allocated
by this product. To determine the correct storage for this data set, add the storage size given in
this table to those given in other tables (perhaps in other program directories). If the data set
already exists, it must have enough free space to accommodate the storage size given in this table.
If you currently have a previous release of Zowe installed in these libraries, the installation of this
release will delete the old release and reclaim the space that was used by the old release and any
service that had been installed. You can determine whether these libraries have enough space by
 deleting the old release with a dummy function, compressing the libraries, and comparing the
space requirements with the free space in the libraries.
For more information about the names and sizes of the required data sets, see Allocate SMP/E
target and distribution libraries.
. Abbreviations used for the file system path type are as follows.
N - New path, created by this product.
X - Path created by this product, but might already exist from a previous release.
P - Previously existing path, created by another product.
. All target and distribution libraries listed have the following attributes:
The default name of the data set can be changed.
The default block size of the data set can be changed.
The data set can be merged with another data set that has equivalent characteristics.
The data set can be either a PDS or a PDSE, with some exceptions. If the value in the "ORG"
column specifies "PDS", the data set must be a PDS. If the value in "DIR Blks" column specifies
"N/A", the data set must be a PDSE.
. All target libraries listed have the following attributes:
These data sets can be SMS-managed, but they are not required to be SMS-managed.
These data sets are not required to reside on the IPL volume.
The values in the "Member Type" column are not necessarily the actual SMP/E element types that
are identified in the SMPMCS.
. All target libraries that are listed and contain load modules have the following attributes:
These data sets cannot be in the LPA, with some exceptions. If the value in the "Member Type"
column specifies "LPA", it is advised to place the data set in the LPA.
These data sets can be in the LNKLST.
These data sets are not required to be APF-authorized, with some exceptions. If the value in the
"Member Type" column specifies "APF", the data set must be APF-authorized.
Storage requirements for SMP/E work data sets
 Library DDNAME TYPE ORG RECFM LRECL No. of 3390 Trks No. of DIR Blks
SMPWRK6 S PDS FB 80 (300,3000) 50
SYSUT1 U SEQ -- -- (300,3000) 0
In the table above, (20,200) specifies a primary allocation of 20 tracks, and a secondary allocation of 200
tracks.
Storage requirements for SMP/E data sets
Library DDNAME TYPE ORG RECFM LRECL No. of 3390 Trks No. of DIR Blks
SMPPTS S PDSE FB 80 (12000,3000) 50
The following figures describe the target and distribution libraries and file system paths required to install
Zowe. The storage requirements of Zowe must be added to the storage required by other programs that
have data in the same library or path.
Note: Use the data in these tables to determine which libraries can be merged into common data sets. In
addition, since some ALIAS names may not be unique, ensure that no naming conflicts will be introduced
before merging libraries.
Storage requirements for Zowe target libraries
Note: These target libraries are not required for the initial FMID install of Zowe SMP/E but will be required for
subsequent SYSMODS so are included here for future reference.

No. of No.
Library Member Target Type Org RECFM LRECL 3390 of
DDNAME Type Volume Trks DIR
Blks

SZWEAUTH APF Load

Modules ANY U PDSE U 0 15 N/A
SZWESAMP Samples ANY U PDSE FB 80 15 5
Zowe file system paths
DDNAME TYPE Path Name
SZWEZFS X /usr/lpp/zowe/SMPE
Storage requirements for Zowe distribution libraries
Note: These target libraries are not required for the initial alpha drop of Zowe SMP/E but will be required for
subsequent drops so are included here for future reference.
Library DDNAME TYPE ORG RECFM LRECL No. of 3390 Trks No. of DIR Blks
AZWEAUTH U PDSE U 0 15 N/A
AZWESAMP U PDSE FB 80 15 5
AZWEZFS U PDSE VB 6995 12000 30
The following figures list data sets that are not used by Zowe, but are required as input for SMP/E.

Data Set Name TYPE ORG RECFM LRECL No. Trks

of 3390 No. of DIR
Blks
hlq.ZOWE.AZWE002.F1 U PDSE FB 80 5 N/A
hlq.ZOWE.AZWE002.F2 U PDSE FB 80 5 N/A
hlq.ZOWE.AZWE002.F3 U PDSE U 0 30 N/A
hlq.ZOWE.AZWE002.F4 U PDSE VB 6995 9900 N/A
hlq.ZOWE.AZWE002.SMPMCS U SEQ FB 80 1 N/A
z/OS UNIX file system U zFS N/A N/A 28715 N/A
Note: These are temporary data sets, which can be removed after the SMP/E installation.
FMIDs deleted
Installing Zowe might result in the deletion of other FMIDs.
To see which FMIDs will be deleted, examine the ++VER statement in the SMPMCS of the product. If you
do not want to delete these FMIDs now, install Zowe into separate SMP/E target and distribution zones.
Note: These FMIDs are not automatically deleted from the Global Zone. If you want to delete these FMIDs
from the Global Zone, use the SMP/E REJECT NOFMID DELETEFMID command. See the SMP/E Commands
book for details.
Special considerations
Zowe has no special considerations for the target system.

Installation instructions
This section describes the installation method and the step-by-step procedures to install and activate the
functions of Zowe.
Notes:
If you want to install Zowe into its own SMP/E environment, consult the SMP/E manuals for instructions
on creating and initializing the SMPCSI and SMP/E control data sets.
You can use the sample jobs that are provided to perform part or all of the installation tasks. The SMP/E
jobs assume that all DDDEF entries that are required for SMP/E execution have been defined in
appropriate zones.
You can use the SMP/E dialogs instead of the sample jobs to accomplish the SMP/E installation steps.
SMP/E considerations for installing Zowe
Use the SMP/E RECEIVE, APPLY, and ACCEPT commands to install this release of Zowe.
SMP/E options subentry values
The recommended values for certain SMP/E CSI subentries are shown in the following table. Using values
lower than the recommended values can result in failures in the installation. DSSPACE is a subentry in the
GLOBAL options entry. PEMAX is a subentry of the GENERAL entry in the GLOBAL options entry. See the
SMP/E manuals for instructions on updating the global zone.
 Subentry Value Comment
DSSPACE (1200,1200,1400) Space allocation
PEMAX SMP/E Default IBM recommends using the SMP/E default for PEMAX.

Overview of the installation steps

Follow these high-level steps to download and install Zowe Open Source Project (Base).
. Download the Zowe SMP/E package
. Allocate file system to hold web download package
. Upload the download package to the host
. Extract and expand the compress SMPMCS and RELFILEs
. Sample installation jobs
. Create SMP/E environment (optional)
. Perform SMP/E RECEIVE
. Allocate SMP/E target and distribution libraries
. Allocate, create and mount ZSF files (Optional)
. Allocate z/OS UNIX paths
. Create DDDEF Entries
. Perform SMP/E APPLY
. Perform SMP/E ACCEPT
. Run REPORT CROSSZONE
. Cleaning up obsolete data sets, paths, and DDDEFs
Download the Zowe SMP/E package>P>
To download the Zowe SMP/E package, open your web browser and go to the Zowe Download website. Click
the Zowe SMP/E FMID AZWE002 button to save the file to a folder on your desktop.
You will receive one ZIP package on your desktop. Extract the following files from the package. You may
need to use the unzip command at a terminal rather than an unzip utility.
AZWE002.pax.Z (binary)
 The SMP/E input data sets to install Zowe are provided as compressed files in AZWE002.pax.Z. This pax
archive file holds the SMP/E MCS and RELFILEs.
AZWE002.readme.txt (text)
The README file AZWE002.readme.txt is a single JCL file containing a job with the job steps you need
to begin the installation, including comprehensive comments on how to tailor them. There is a sample
job step that executes the z/OS UNIX System Services pax command to extract package archives. This
job also executes the GIMUNZIP program to expand the package archives so that the data sets can be
processed by SMP/E.
AZWE002.hml (text)
The Program Directory for the Zowe Open Source Project.
Allocate file system to hold the download package
You can either create a new z/OS UNIX file system (zFS) or create a new directory in an existing file system
to place AZWE002.pax.Z. The directory that will contain the download package must reside on the z/OS
system where the function will be installed.
To create a new file system, and directory, for the download package, you can use the following sample JCL
(FILESYS).
Copy and paste the sample JCL into a separate data set, uncomment the job, and modify the job to update
required parameters before submitting it.
Expected Return Codes and Messages: You will receive a return code of 0 if this job runs correctly.
Upload the download package to the host
Upload the AZWE002.readme.txt file in text format and the AZWE002.pax.Z file in binary format from your
workstation to the z/OS UNIX file system. The instructions in this section are also in the
AZWE002.readme.txt file that you downloaded.
Note: Ensure you download the pax file in a different file system than where you put Zowe runtime.
There are many ways to transfer the files or make them available to the z/OS system where the package will
be installed. In the following sample dialog, we use FTP from a Microsoft Windows command line to do the
transfer. This assumes that the z/OS host is configured as an FTP host/server and that the workstation is an
FTP client. Commands or other information entered by the user are in bold, and the following values are
assumed.
If you are not sure which protocol or port to use to transfer the files or any access that might be needed, you
may need to consult with the network administrator.
User Values
enters:
mvsaddr TCP/IP address or hostname of the z/OS system
tsouid Your TSO user ID
tsopw Your TSO password
d: Location of the downloaded files

@zfs_path@ z/OS UNIX path where to store the files. This matches the @zfs_path@ variable you
specified in the previous step.
Important! The AZWE002.pax.Z file must be uploaded to the z/OS driving system in binary format, or the
subsequent UNPAX step will fail.
This step of tranferring the files can take a long time to run, depending on the capacity of your system, and
on what other jobs are running.
Sample FTP upload scenario:
If you are unable to connect with ftp and only able to use sftp, the commands above are the same
except that you will use sftp at the command prompt instead of ftp. Also, because sftp only supports binary
file transfer, the ascii and binary commands should be omitted. After you transfer the AZWE002.readme.txt
file, it will be in an ASCII codepage so you need to convert it to EBCDIC before it can be used. To convert
AZWE002.readme.txt to EBCDIC, log in to the distribution system using ssh and run an ICONV command.
_C:>/ssh tsouid@mvsaddr_
_tsouid@mvsaddr's password: tsopw_
/u/tsouid:>
cd:@zfs_path@
@zfs_path:>
@zfs_path:>iconv -f ISO8859-1 -t IBM-1047 AZWE002.readme.txt > AZWE002.readme.EBCDIC
@zfs_path:>rm AZWE002.readme.txt
@zfs_path:>mv AZWE002.readme.EBCDIC AZWE002.readme.txt
@zfs_path:>exit
C:>/
Extract and expand the compressed SMPMCS and RELFILEs
The AZWE002.readme.txt file uploaded in the previous step holds a sample JCL to expand the compressed
SMPMCS and RELFILEs from the uploaded AZWE002.pax.Z file into data sets for use by the SMP/E RECEIVE
job. The JCL is repeated here for your convenience.
@zfs_path@ matches the variable that you specified in the previous step.
If the oshell command gets a RC=256 and message "pax: checksum error on tape (got ee2e,
expected 0)", then the archive file was not uploaded to the host in binary format.
GIMUNZIP allocates data sets to match the definitions of the original data sets. You might encounter
errors if your SMS ACS routines alter the attributes used by GIMUNZIP. If this occurs, specify a non-
SMS managed volume for the GINUMZIP allocation of the data sets. For example:
Normally, your Automatic Class Selection (ACS) routines decide which volumes to use. Depending on
your ACS configuration, and whether your system has constraints on disk space, units, or volumes,
some supplied SMP/E jobs might fail due to volume allocation errors. See GIMUNZIP for more details.
GIMUNZIP
The GIMUNZIP job may issue allocation error messages for SYSUT1 similar to these:
The job will end with RC=12. If this happens, add a TEMPDS control statement to the existing SYSIN as
shown below:
where, &VOLSER is a DISK volume with sufficient free space to hold temporary copies of the RELFILES. As
a guide, this may require 1,000 cylinders, or about 650 MB.
Sample installation jobs
The following sample installation jobs are provided in hlq.ZOWE.AZWE002.F1 , or equivalent, as part of
the project to help you install Zowe:
 Job Name Job Type Description RELFILE

ZWE1SMPE SMP/E (Optional) Sample job to create an SMP/E ZOWE.AZWE002.F1

environment
ZWE2RCVE RECEIVE Sample SMP/E RECEIVE job ZOWE.AZWE002.F1

ZWE3ALOC ALLOCATE Sample

libraries
job to allocate target and distribution ZOWE.AZWE002.F1

ZWE4ZFS ALLOMZFS (Optional) Sample job to allocate, create

mountpoint, and mount zFS data sets ZOWE.AZWE002.F1

ZWE5MKD MKDIR Sample job to invoke the supplied ZWEMKDIR ZOWE.AZWE002.F1

EXEC to allocate file system paths
ZWE6DDEF DDDEF Sample job to define SMP/E DDDEFs ZOWE.AZWE002.F1
ZWE7APLY APPLY Sample SMP/E APPLY job ZOWE.AZWE002.F1
ZWE8ACPT ACCEPT Sample SMP/E ACCEPT job ZOWE.AZWE002.F1
Note: When Zowe is downloaded from the web, the RELFILE data set name will be prefixed by your chosen
high-level qualifier, as documented in the Extract and expand the compressed SMPMCS and RELFILEs
section.
You can access the sample installation jobs by performing an SMP/E RECEIVE (refer to Perform SMP/E
RECEIVE), then copy the jobs from the RELFILES to a work data set for editing and submission.
You can also copy the sample installation jobs from the product files by submitting the following job. Before
you submit the job, add a job statement and change the lowercase parameters to uppercase values to meet
the requirements of your site.
See the following information to update the statements in the sample above:
IN:
filevol is the volume serial of the DASD device where the downloaded files reside.
 OUT:
jcl-library-name is the name of the output data set where the sample jobs are stored.
dasdvol is the volume serial of the DASD device where the output data set resides. Uncomment
the statement is a volume serial must be provided.
The following supplied jobs might fail due to disk space allocation errors, as mentioned above for GIMUNZIP.
Review the following sections for example error and actions that you can take to resolve the error.
ZWE2RCVE
ZWE1SMPE and ZWE4ZFS
ZWEMKDIR, ZWE1SMPE, ZWE2RCVE, ZWE3ALOC, ZWE4ZFS and ZWE5MKD
ZWE2RCVE
Add space and directory allocations to this SMPCNTL statement in the preceding ZWE1SMPE job:
This makes it as below:
ZWE1SMPE and ZWE4ZFS
Example error
Uncomment the VOLUMES(...) control statements and refer to the comments at the start of the JCL job
for related necessary changes.
ZWEMKDIR, ZWE1SMPE, ZWE2RCVE, ZWE3ALOC, ZWE4ZFS and ZWE5MKD
Example error
Uncomment the VOL=SER=&... control statements and refer to the comments at the start of the JCL job
for related necessary changes.
Create SMP/E environment (Optional)
A sample job ZWE1SMPE is provided or you may choose to use your own JCL. If you are using an existing
CSI, do not run the sample job ZWE1SMPE. If you choose to use the sample job provided, edit and submit
ZWE1SMPE. Consult the instructions in the sample job for more information.
Note: If you want to use the default of letting your Automatic Class Selection (ACS) routines decide which
volume to use, comment out the following line in the sample job ZWE1SMPE.
// SET CSIVOL=#csivol

Expected Return Codes and Messages: You will receive a return code of 0 if this job runs correctly.
Perform SMP/E RECEIVE
Edit and submit sample job ZWE2RCVE to perform the SMP/E RECEIVE for Zowe. Consult the instructions in
the sample job for more information.
Expected Return Codes and Messages: You will receive a return code of 0 if this job runs correctly.
Allocate SMP/E target and distributions libraries
Edit and submit sample job ZWE3ALOC to allocate the SMP/E target and distribution libraries for Zowe.
Consult the instructions in the sample job for more information.
Expected Return Codes and Messages: You will receive a return code of 0 if this job runs correctly.
Allocate, create and mount ZSF files (Optional)
This job allocates, creates a mountpoint, and mounts zFS data sets.
If you plan to install Zowe into a new z/OS UNIX file system, you can edit and submit the optional ZWE4ZFS
job to perform the following tasks. Consult the instructions in the sample job for more information.
Create the z/OS UNIX file system
Create a mountpoint
Mount the z/OS UNIX file system on the mountpoint
The recommended z/OS UNIX file system type is zFS. The recommended mountpoint is /usr/lpp/zowe.
Before running the sample job to create the z/OS UNIX file system, you must ensure that OMVS is active on
the driving system. zFS must be active on the driving system if you are installing Zowe into a file system that
is zFS.
If you create a new file system for this product, consider updating the BPXPRMxx PARMLIB member to
mount the new file system at IPL time. This action can be helpful if an IPL occurs before the installation is
completed.
See the following information to update the statements in the previous sample:
#dsn is the name of the data set holding the z/OS UNIX file system.
/usr/lpp/zowe is the name of the mountpoint where the z/OS UNIX file system will be mounted.
Expected Return Codes and Messages: You will receive a return code of 0 if this job runs correctly.
Allocate z/OS UNIX paths
The target system HFS or zFS data set must be mounted on the driving system when running the sample
ZWE5MKD job since the job will create paths in the HFS or zFS.
Before running the sample job to create the paths in the file system, you must ensure that OMVS is active on
the driving system and that the target system's HFS or zFS file system is mounted on the driving system.
zFS must be active on the driving system if you are installing Zowe into a file system that is zFS.
If you plan to install Zowe into a new HFS or zFS file system, you must create the mountpoint and mount the
new file system on the driving system for Zowe.
The recommended mountpoint is /usr/lpp/zowe.
Edit and submit sample job ZWE5MKD to allocate the HFS or zFS paths for Zowe. Consult the instructions in
the sample job for more information.
If you create a new file system for this product, consider updating the BPXPRMxx PARMLIB member to
mount the new file system at IPL time. This action can be helpful if an IPL occurs before the installation is
completed.
Expected Return Codes and Messages: You will receive a return code of 0 if this job runs correctly.
Create DDDEF entries
Edit and submit sample job ZWE6DDEF to create DDDEF entries for the SMP/E target and distribution
libraries for Zowe. Consult the instructions in the sample job for more information.
Expected Return Codes and Messages: You will receive a return code of 0 if this job runs correctly.
Perform SMP/E APPLY
In this step, you run the sample job ZWE7APLY to apply Zowe. This step can take a long time to run,
depending on the capacity of your system, and on what other jobs are running.
Follow these steps
. Ensure that you have the latest HOLDDATA; then edit and submit sample job ZWE7APLY to perform an
SMP/E APPLY CHECK for Zowe. Consult the instructions in the sample job for more information.
The latest HOLDDATA is available through several different portals, including
http://service.software.ibm.com/holdata/390holddata.html. The latest HOLDDATA may identify HIPER
and FIXCAT APARs for the FMIDs you will be installing. An APPLY CHECK will help you determine
whether any HIPER or FIXCAT APARs are applicable to the FMIDs you are installing. If there are any
applicable HIPER of FIXCAT APARs, the APPLY CHECK will also identify fixing PTFs that will resolve the
APARs, if a fixing PTF is available.
You should install the FMIDs regardless of the status of unresolved HIPER or FIXCAT APARs. However,
do not deploy the software until the unresolved HIPER and FIXCAT APARs have been analyzed to
determine their applicability. That is, before deploying the software either ensure fixing PTFs are applied
to resolve all HIPER or FIXCAT APARs, or ensure the problems reported by all HIPER or FIXCAT APARs
are not applicable to your environment.
To receive the full benefit of the SMP/E Causer SYSMOD Summary Report, do not bypass the PRE, ID,
REQ, and IFREQ on the APPLY CHECK. The SMP/E root cause analysis identifies the cause only of errors
and not of warnings (SMP/E treats bypassed PRE, ID, REQ, and IFREQ conditions as warnings, instead of
errors).
Here are sample APPLY commands:
i. To ensure that all recommended and critical service is installed with the FMIDs, receive the latest
HOLDDATA and use the APPLY CHECK command as follows
Some HIPER APARs might not have fixing PTFs available yet. You should analyze the symptom
flags for the unresolved HIPER APARs to determine if the reported problem is applicable to your
environment and if you should bypass the specific ERROR HOLDs in order to continue the
installation of the FMIDs.
This method requires more initial research, but can provide resolution for all HPERs that have fixing
PTFs available and not in a PE chain. Unresolved PEs or HIPERs might still exist and require the use
of BYPASS.
 ii. To install the FMIDs without regard for unresolved HIPER APARs, you can add the
BYPASS(HOLDCLASS(HIPER)) operand to the APPLY CHECK command. This will allow you to
install FMIDs, even though one of more unresolved HIPER APARs exist. After the FMIDs are
installed, use the SMP/E REPORT ERRSYSMODS command to identify unresolved HIPER APARs
and any fixing PTFs.
This method is quicker, but requires subsequent review of the Exception SYSMOD report produced
by the REPORT ERRSYSMODS command to investigate any unresolved HIPERs. If you have
received the latest HOLDDATA, you can also choose to use the REPORT MISSINGFIX command
and specify Fix Category IBM.PRODUCTINSTALL-REQUIREDSERVICE to investigate missing
recommended service.
If you bypass HOLDs during the installation of the FMIDs because fixing PTFs are not yet available,
you can be notified when the fixing PTFs are available by using the APAR Status Tracking (AST)
function of the ServiceLink or the APAR Tracking function of Resource Link.
. After you take actions that are indicated by the APPLY CHECK, remove the CHECK operand and run the
job again to perform the APPLY.
Note: The GROUPEXTENDED operand indicates the SMP/E applies all requisite SYSMODs. The requisite
SYSMODS might be applicable to other functions.
Expected Return Codes and Messages from APPLY CHECK: You will receive a return code of 0 if the job
runs correctly.
Expected Return Codes and Messages from APPLY: You will receive a return code of 0 if the job runs
correctly.
Perform SMP/E ACCEPT
Edit and submit sample job ZWE8ACPT to perform an SMP/E ACCEPT CHECK for Zowe. Consult the
instructions in the sample job for more information.
To receive the full benefit of the SMP/E Causer SYSMOD Summary Report, do not bypass the PRE, ID, REQ,
and IFREQ on the ACCEPT CHECK. The SMP/E root cause analysis identifies the cause of errors but not
warnings (SMP/E treats bypassed PRE, ID, REQ, and IFREQ conditions as warnings rather than errors).
Before you use SMP/E to load new distribution libraries, it is recommended that you set the ACCJCLIN
indicator in the distribution zone. In this way, you can save the entries that are produced from JCLIN in the
distribution zone whenever a SYSMOD that contains inline JCLIN is accepted. For more information about
the ACCJCLIN indicator, see the description of inline JCLIN in the SMP/E Commands book for details.
After you take actions that are indicated by the ACCEPT CHECK, remove the CHECK operand and run the
job again to perform the ACCEPT.
Note: The GROUPEXTEND operand indicates that SMP/E accepts all requisite SYSMODs. The requisite
SYSMODS might be applicable to other functions.
Expected Return Codes and Messages from ACCEPT CHECK: You will receive a return code of 0 if this
job runs correctly.
If PTFs that contain replacement modules are accepted, SMP/E ACCEPT processing will link-edit or bind the
modules into the distribution libraries. During this processing, the Linkage Editor or Binder might issue
messages that indicate unresolved external references, which will result in a return code of 4 during the
ACCEPT phase. You can ignore these messages, because the distribution libraries are not executable and
the unresolved external references do not affect the executable system libraries.
Expected Return Codes and Messages from ACCEPT: You will receive a return code of 0 if this job runs
correctly.
Run REPORT CROSSZONE
The SMP/E REPORT CROSSZONE command identifies requisites for products that are installed in separate
zones. This command also creates APPLY and ACCEPT commands in the SMPPUNCH data set. You can use
the APPLY and ACCEPT commands to install those cross-zone requisites that the SMP/E REPORT
CROSSZONE command identifies.
After you install Zowe, it is recommended that you run REPORT CROSSZONE against the new or updated
target and distribution zones. REPORT CROSSZONE requires a global zone with ZONEINDEX entries that
describe all the target and distribution libraries to be reported on.
For more information about REPORT CROSSZONE, see the SMP/E manuals.
Cleaning up obsolete data sets, paths, and DDDEFs
The web download data sets listed in DASD storage requirements are temporary data sets. You can delete
these data sets after you complete the SMP/E installation.
Activating Zowe
File system execution
If you mount the file system in which you have installed Zowe in read-only mode during execution, then you
do not have to take further actions to activate Zowe.

Zowe customization
You can find the necessary information about customizing and using Zowe on the Zowe doc site.
For more information about how to customize Zowe, see Configuring Zowe after installation.
For more information about how to use Zowe, see Using Zowe.
Installing Zowe SMP/E build with z/OSMF
Version: v2.0.x LTS

workflow
z/OSMF workflow simplifies the procedure to create an SMP/E environment for Zowe. Register and execute
the Zowe SMP/E workflow to create SMP/E environment in the z/OSMF web interface. Perform the following
steps to register and execute the Zowe workflow in the z/OSMF web interface:
. Log in to the z/OSMF web interface.
. Select Workflows from the navigation tree.
. Select Create Workflow from the Actions menu.
. Enter the complete path to the workflow definition file in the Workflow Definition filed.
The workflow is located in the ZWEWRF01 member of the hlq.ZOWE.AZWE002.F4 data set.
. (Optional) Enter the path to the customized variable input file that you prepared in advance.
The variable input file is located in ZWEYML01 member of the hlq.ZOWE.AZWE002 data set.
Create a copy of the variable input file. Modify the file as necessary according to the built-in comments.
Set the field to the path where the new file is located. When you execute the workflow, the values from
the variable input file override the workflow variables default values.
. Select the system where you want to execute the workflow.
. Select Next.
. Specify the unique workflow name.
. Select or enter an Owner Use ID and select Assign all steps to owner user ID.
. Select Finish.
The workflow is registered in z/OSMF and ready to execute.
. Select the workflow that you registered from the workflow list.
 . Execute the steps in order.
For general information about how to execute z/OSMF workflow steps, watch the z/OSMF Workflows
Tutorial.
. Perform the following steps to execute each step individually:
i. Double-click the title of the step.
ii. Select the Perform tab.
iii. Review the step contents and update the input values as required.
iv. Select Next.
v. Repeat the previous two steps to complete all items until the option Finish is available.
vi. Select Finish.
After you execute each step, the step is marked as Complete. The workflow is executed.
After you complete executing all the steps individually, the Zowe SMP/E is created.

Activating Zowe
File system execution
If you mount the file system in which you have installed Zowe in read-only mode during execution, then you
do not have to take further actions to activate Zowe.

Zowe customization
You can find the necessary information about customizing and using Zowe on the Zowe doc site.
For more information about how to customize Zowe, see Configuring Zowe after installation.
For more information about how to use Zowe, see Using Zowe.
Installing Zowe from a Portable Software
Version: v2.0.x LTS

Instance
As a systems programmer, your responsibilities include acquiring, installing, maintaining, and configuring
mainframe products on your systems. z/OSMF lets you perform these tasks. z/OSMF lets you manage
software on your z/OS systems through a browser at any time, from any location. By streamlining some
traditional tasks and automating others, z/OSMF can simplify some areas of system management and also
reduce the level of expertise that is required for managing system activities. Experienced users can view,
define, and update policies that affect system behavior, monitor system performance, and manage their
z/OS software. As products and vendors adopt z/OSMF services, you can install and maintain all your
mainframe products in a common way according to industry best practices. After configuration is complete,
you can execute the product and easily provision new software instances for use on other systems
throughout your environment.

Prerequisites
To install Zowe using z/OSMF, ensure that you meet the following requirements:
z/OSMF 2.3 or higher
1.2GB of free space
READ access to data set names with the HLQ ZWE on the user ID you use to deploy the portable
package

Procedure
Refer to the following subpages to guide you through the installation procedure using z/OSMF.
Address z/OSMF Requirements
Provides information about z/OSMF general configuration and security requirements.
Acquire a z/OSMF Portable Software Instance
Provides the steps to acquire the product software by downloading the z/OSMF portable software
instance to the z/OSMF host. You must then register the portable software instance in z/OSMF.
Install Product Software Using z/OSMF Deployments
Provides the steps to install (deploy) the portable software instance to an LPAR using z/OSMF
 Deployments. This step creates the SMP/E environment and runs the RECEIVE, APPLY, and ACCEPT
steps to prepare the software instance for SMP/E operations. This step also:
When these tasks are completed, you are ready to install preventive maintenance.
Address z/OSMF Requirements
Version: v2.0.x LTS

Before you install Zowe using IBM z/OSMF, address the following installation and security requirements. Your
systems programmers and security administrators can complete these tasks in parallel.
Apply required maintenance for Common Components and Services for z/OS (CCS) Version 15.0
(SO12499)
Role: Systems programmer
The CCS PTF installs load module stubs for select IBM products into your installed CCS library
hlq.ZWE0CALL. If you are prompted during installation for the data set name of a load library for an
IBM product that is not installed, specify your installed hlq.ZWE0CALL data set name.
Configure z/OSMF
Role: Systems programmer, security administrator, domain administrator
The IBM z/OS Management Facility Configuration Guide is your primary source of information
about how to configure z/OSMF. You can open the IBM documentation in a separate browser tab
for reference during installation of your products using z/OSMF Deployments. To prevent
configuration errors and to enable z/OSMF Software Update for maintenance, apply all z/OSMF
related maintenance before you begin the installation process.
Configure z/OSMF security
Role: Security administrator
Configure z/OSMF security for ACF2, Top Secret, or IBM RACF as applicable to authorize users and
resources. To prevent SSL handshake failures when importing product information into z/OSMF,
make sure that you have added the Digicert Intermediate CA certificate to the z/OSMF keyring. For
information, see Import Product Information into z/OSMF.
Confirm that the installer has read, create, update, and execute privileges in z/OS
Role: Security administrator
Write access is also required to the UNIX System Services (USS) directories that are used for the
installation process. To deploy a product that has USS components, the installer's user ID must
have access to the appropriate resource profiles in the UNIXPRIV class, access to the
BPX.SUPERUSER resource profile in the FACILITY class, or UID(0). For UNIXPRIV, read access is
 required to SUPERUSER.FILESYS.CHOWN, SUPERUSER.FILESYS.CHGRP, and
SUPERUSER.FILESYS.MOUNT.
Address USS requirements
Role: Systems programmer, security administrator
Address the following USS requirements:
Create a USS directory to receive the z/OSMF pax file and to perform the unpack steps.
Confirm that you have write authority to the USS directories that are used for the z/OSMF pax
installation process.
Confirm that you have available USS file space.
To download and unpack the pax file, you need free space that is approximately 3.5 times the pax
file size in the file system that contains the pax directories. For example, to download and unpack a
14-MB pax file, you need approximately 49 MB of free space in the file system hosting your pax
directory. If you do not have sufficient free space, error messages like EZA1490I Error writing to
data set or EZA2606W File I/O error 133 can occur.
Configure SMP/E Internet Service Retrieval
Role: Systems programmer, security administrator
Configure SMP/E Internet Service Retrieval to receive and download maintenance on a regular
cadence or build custom maintenance packages (order PTFs, APARs, critical, recommended, all, or
just HOLDDATA). This step is our recommended best practice when installing maintenance and is
required to use the z/OSMF Software Update. For configuration details, see the Mainframe
Common Maintenance Procedures documentation.
After these requirements have been addressed, you are ready to acquire a z/OSMF Portable Software
Instance or Configure a Software Instance using z/OSMF Workflows.
Acquire a z/OSMF Portable Software
Version: v2.0.x LTS

Instance
As a systems programmer, you can acquire an IBM z/OSMF portable package for your product and then add
the portable software instance to z/OSMF. The product SMP/E environments are pre-built, backed up, and
made available for download as a z/OSMF portable software instance. After you acquire the portable
software instance, you can use z/OSMF Deployments to perform the installation and z/OSMF workflows to
perform post-install configuration.
When you complete the acquisition process, the product software is ready for installation using z/OSMF
Deployments.
Note: Before you begin the acquisition process, ensure that you address the z/OSMF requirements.
The z/OSMF product acquisition process consists of the following tasks.
. Download the portable software instance from Zowe downloads and transfer it to the mainframe.
. Register the portable software instance in z/OSMF.
Refer to the sections below for instructions.

Download the Portable Software Instance from Zowe

Downloads
To acquire the portable software instance, you download it from the Zowe Downloads page and transfer it to
a local z/OSMF host using a file transfer utility, such as FTP.
The portable software instance is a portable form of a software instance, including the SMP/E CSI data sets,
all associated SMP/E-managed target and distribution libraries, non-SMP/E-managed data sets, and meta-
data that is required to describe the product software instance.
. Go to Zowe Downloads and find Zowe - Portable Software Instance.
. Download the latest version of the package to your workstation.
. Use an file transfer utility such as an FTP client to transfer the single pax file to the mainframe.
 . Execute the JCL to unpack the installation file and restore the individual pax files. Sample JCL follows:
//USSBATCH EXEC PGM=BPXBATCH
//STDOUT DD SYSOUT=* //STDERR DD SYSOUT=* //STDPARM DD * sh cd
/yourUSSpaxdirectory/;
pax -rvf yourpaxfilename.ZOSMF.pax.Z
/*
Customize the sample JCL as follows and then submit for execution:
USSBATCH can take several minutes to execute. A return code of zero is expected. Any other return
code indicates a problem.
After successful execution, the individual pax files are restored and ready for use. Go to Register Portable
Software Instance in z/OSMF.

Register Portable Software Instance in z/OSMF

After you have acquired and downloaded the portable software instance to a local z/OSMF host system, you
must log in to z/OSMF to register the product software and define the portable software instance to z/OSMF
as shown in the following procedure. When you complete these steps, the portable software instance is
registered in z/OSMF and ready for installation (deployment).
. Log in to the z/OSMF web interface and select your user ID in the top or bottom right-hand corner to
switch between the Desktop Interface and Classic Interface.
. Complete either of the following steps to display the Software Management page:
i. In the Desktop Interface, select Software Management.
ii. In the Classic Interface, select Software, Software Management.
. Select Portable Software Instances to define your portable software instance to z/OSMF.
. Select Add from the Actions menu and select From z/OSMF System.
The Add Portable Software Instance page displays.
. Select or type the system name (destination LPAR) and UNIX directory (destination USS directory)
where the portable software instance files reside and select Retrieve.
. Enter a name for the new portable software instance. You can also enter an optional description and
assign one or more categories that display existing packages.
. Select OK.
The new portable software instance is now defined to z/OSMF.
The portable software instance is now registered in z/OSMF and ready to install (deploy).
Install Product Software Using z/OSMF
Version: v2.0.x LTS

Deployments
As a systems programmer, your responsibilities include installing product software in your z/OS environment.
After the portable software instance or software instance is registered in z/OSMF, you can use z/OSMF
Deployments to install the product software and create the product data sets (global, CSI, target libraries,
and distribution libraries) for the new software instance. The deployment jobs create a copy of the source
product data sets to create the product target runtime environment. Creating a copy of the SMP/E target
data sets keeps the SMP/E environment clean and it also isolates the product runtime environment for
maintenance activities. You can also perform z/OSMF workflows to customize the SMP/E data sets, mount
UNIX System Services (USS) files if necessary, and configure the new software instance on the target
system.
To install Zowe PSWI using z/OSMF and make the product software available for use on a system by users
and other programs, define a new deployment. This step defines the SMP/E environment name and the
prefix of the CSI data set in z/OSMF. You also specify data set allocation parameters for all SMP/E data sets,
target libraries, and distribution libraries. To define a new deployment, complete the deployment checklist
(specify the USS path, DSN, VOLSERs), and submit the deployment jobs through the z/OSMF user interface.
When the deployment is complete, you have a source and target copy of the software.
For more information about these tasks, see Deploying software in the IBM documentation.
Subsequent maintenance activities for the product update the SMP/E environment without affecting your
active product runtime environments. You decide when to redeploy the maintenance-updated SMP/E target
data sets to each of the product runtime environments.
Note: The installer requires read, create, update, and execute privileges in z/OS. Write access is also
required to the USS directories that are used for the installation process. To deploy a product that has USS
components, the installer's user ID must have access to the appropriate resource profiles in the UNIXPRIV
class, access to the BPX.SUPERUSER resource profile in the FACILITY class, or UID(0). For UNIXPRIV, read
access is required to SUPERUSER.FILESYS.CHOWN, SUPERUSER.FILESYS.CHGRP, and
SUPERUSER.FILESYS.MOUNT.
. Display the Deployments table in z/OSMF (Software ManagementU, Deployments).
. Define a new deployment by selecting New from the Actions menu.
The deployment checklist displays. You can also modify, view, copy, cancel, or remove existing
 deployments.
. Complete the deployment checklist items as described in Defining new deployments in the IBM
documentation.
As you complete the deployment checklist, be sure to make the following selections:
The deployment process is complete. The new software instance is defined to z/OSMF. You are now ready to
Import Product Information into z/OSMF before you install product maintenance.
Initializing the z/OS system
Version: v2.0.x LTS

After you install the Zowe runtime, you must initialize Zowe with proper security configurations, certificates,
and so on before you can start it. To do this, you run the zwe init command. This step is common for
installing and configuring Zowe from either a convenience build or from an SMP/E build.

About the zwe init command

The zwe init command is a combination of the following sub-commands. Each sub-command defines a
configuration.
mvs : Copy the data sets provided with Zowe to custom data sets.

security : Create the user IDs and security manager settings.

apfauth : APF authorize the LOADLIB containing the modules that need to perform z/OS priviledged
security calls.
certificate : Configure Zowe to use TLS certificates.

vsam : Configure the VSAM files needed to run the Zowe caching service used for high availability (HA)

stc : Configure the system to launch the Zowe started task.

You can type zwe init --help to learn more about the command or see the zwe init command
reference for detailed explanation, examples, and parameters.
zwe init command requires a Zowe configuration file to proceed. This configuration file instructs how
Zowe should be initialized. Please create and review this file before proceeding.

Procedure
To initialize the z/OS system and permissions that Zowe requires, run the following command.

Next steps
The zwe init command runs the sub-commands in sequence automatically. If you have successfully ran
the above command, you can move on to start Zowe.
You can choose to run the sub-commands one by one to define each step based on your need, or if you
encounter some failures with zwe init command, you can pick up the failed sub-commands step
specifically and re-run it.
. Prepare custom MVS data sets. Copy the data sets provided with Zowe to custom data sets.
. Initialize Zowe security configurations. Create the user IDs and security manager settings.
If Zowe has already been launched on a z/OS system from a previous release of Zowe v2 you can skip
this security configuration step unless told otherwise in the release documentation.
. APF authorize load libraries containing the modules that need to perform z/OS privileged security calls..
. Configure Zowe to use TLS certificates.
. (Required only if you are configuring Zowe for cross LPAR sysplex high availability): Create the VSAM
data sets used by the Zowe API Mediation Layer caching service.
. Install Zowe main started tassks.
To learn how to run the zwe init command step by step, type zwe init <sub-command> --help .
For example, zwe init stc --help .
Initializing Zowe custom data sets
Version: v2.0.x LTS

Learn how to intialize Zowe custom MVS data sets by using the zwe init mvs command.

Introduction
During the installation of Zowe, three data sets SZWEAUTH , SZWESAMP and SZWEEXEC are created and
populated with members copied across from the Zowe installation files. The contents of these data sets
represent the original files that were provided as part of the Zowe installation and are not meant to be
modified because they will be replaced during subsequent upgrades of Zowe version 2.
For modification and execution, you must create custom data sets by using the zwe init mvs command.
For detailed information about this command, see the zwe init mvs command reference.
The zowe.yaml section that contains the parameters for the data set names is:
The storage requirements for the three data sets are included here.

Library Member zowe.yaml Target Type Org RECF

DDNAME Type Volume

PARM
CUST.PARMLIB Library zowe.setup.dataset.parmlib ANY U PDSE FB
Members
CUST.JCLLIB JCL
Members zowe.setup.dataset.jcllib ANY U PDSE FB

CLIST
CUST.ZWESAPL copy zowe.setup.dataset.authPluginLib ANY U PDSE U
utilities
Procedure
To initialize Zowe custom data sets, run the following command:
Here is an example of running zwe init mvs .

Results
If this step is successful, there will be three custom data sets matching the values in
zowe.setup.dataset.parmlib , zowe.setup.dataset.jcllib and
zowe.setup.dataset.authPluginLib in the zowe.yaml file. The member ZWESIP00 will exist in
the CUST.PARMLIB and the JCLLIB and ZWESAPL will be empty.
In addition to the three custom data sets, the PDS SZWEAUTH is created. This may already exist. In this
case, you will receive the error message Error ZWEL0158E: IBMUSER.ZWEV2.SZWEAUTH already
exists . You can ignore this message, or you can use the --allow-overwritten option on the
command. For example, zwe init mvs -c zowe.yaml --allow-overwritten .
Initialize Zowe security configurations
Version: v2.0.x LTS

This security configuration step is required for first time setup of Zowe. If Zowe has already been launched
on a z/OS system from a previous release of Zowe v2, you can skip this step unless told otherwise in the
release documentation.
The JCL member .SZWESAMP(ZWESECUR) is provided to assist with the security configuration. Before
submitting the ZWESECUR JCL member, you should customize it to match site security rules. For script
driven scenarios, you can run the command zwe init security which uses ZWESECUR as a template
to create a customized member in .CUST.JCLLIB which contains the commands needed to perform the
security configuration.

Configuring with zwe init security command

The zwe init security command reads data from zowe.yaml and will construct a JCL member
using ZWESECUR as a template which is then submitted. This is a convenience step to assist with driving
Zowe configuration through a pipeline or when you prefer to use USS commands rather than directly edit
and customize JCL members.
Specify the parameter --security-dry-run to construct a JCL member containing the security
commmands without running it. This is useful for previewing commands and can also be used to copy and
paste commands into a TSO command prompt for step by step manual execution. Here is an example:

Configuring with ZWESECUR JCL

You may skip using zwe init security to prepare a JCL member to configure the z/OS system, and
edit ZWESECUR directly to make changes.
The JCL allows you to vary which security manager you use by setting the PRODUCT variable to be one of
RACF , ACF2 , or TSS .

If ZWESECUR encounters an error or a step that has already been performed, it will continue to the end, so
it can be run repeatedly in a scenario such as a pipeline automating the configuration of a z/OS environment
for Zowe installation.
It is expected that the security administrator at a site will want to review, edit where necessary, and either
execute ZWESECUR as a single job or else execute individual TSO commands one by one to complete the
security configuration of a z/OS system in preparation for installing and running Zowe.
The following video shows how to locate the ZWESECUR JCL member and execute it.

Undo security configurations

If you want to undo all of the z/OS security configuration steps performed by the JCL member ZWESECUR ,
Zowe provides a reverse member ZWENOSEC that contains the inverse steps that ZWESECUR performs.
This is useful in the following situations:
You are configuring z/OS systems as part of a build pipeline that you want to undo and redo
configuration and installation of Zowe using automation.
You have configured a z/OS system for Zowe that you no longer want to use and you prefer to delete
the Zowe user IDs and undo the security configuration settings rather than leave them enabled.
If you run ZWENOSEC on a z/OS system, then you will no longer be able to run Zowe until you rerun
ZWESECUR to reinitialize the z/OS security configuration.

Next steps
The ZWESECUR JCL does not perform the following initialization steps so after you run ZWESECUR , you
must complete these steps manually to further configure your z/OS environment.
Perform APF authorization of Zowe load libraries that require access to make privileged calls
Copy the JCL members for Zowe's started tasks to a PDS on proclib concatenation path
Create VSAM data sets used by the Zowe caching service
Grant users permission to access z/OSMF
Configure an ICSF cryptographic services environment
Configure multi-user address space (for TSS only)
The ZWESECUR JCL performs the following initialization steps so you do not need to perform them
manually if you have successfully run the JCL. However, if you prefer to manually configure the z/OS
environment, you must complete the following steps next.
User IDs and groups for the Zowe started tasks
Configure ZWESLSTC to run high availability instances under ZWESVUSR user ID
Configure the cross memory server for SAF
Configuring the z/OS system for Zowe
Version: v2.0.x LTS

Learn how to configure the z/OS system for Zowe. Before you begin, check the following table to understand
which steps you need to perform based on your settings.
Configuration step Purpose
Configure an ICSF Required if you want to use Zowe desktop. This step will generate
cryptographic services random numbers for zssServer that the Zowe desktop uses.
environment
Configure security Required if you want to allow users to log on to the Zowe desktop
environment switching through impersonation.
Configure address space Required if you want to set the names for the different z/OS UNIX
job naming address spaces for the Zowe runtime components.
Configure multi-user Required for TSS only. A TSS FACILITY needs to be defined and assigned
address space for TSS only to the ZWESLSTC started task.
Configure user IDs and
groups for the Zowe started Required if you have not run ZWESECUR and are manually creating the
user ID and groups in your z/OS environment.
tasks
Configure ZWESLSTC to Required if you have not run ZWESECUR and are configuring your z/OS
run Zowe high availability environment manually. This step describes how to configure the started
instances under task ZWESLSTC to run under the correct user ID and group.
ZWESVUSR user ID
Required if you have not run ZWESECUR and are configuring your z/OS
Configure the cross environment manually. This step describes how to configure the cross
memory server for SAF memory server for SAF to guard against access by non-priviledged
clients.
 Configuration step Purpose
Configure main Zowe Required for API Mediation Layer to map client certificate to a z/OS
server to use identity identity.
mapping
Configure signed SAF Required to configure SAF Identity tokens on z/OS so that they can be
Identity tokens IDT used by Zowe components like zss or API Mediation Layer.

Configure an ICSF cryptographic services environment

The zssServer uses cookies that require random number generation for security. To learn more about the
zssServer, see the Zowe architecture. Integrated Cryptographic Service Facility (ICSF) is a secure way to
generate random numbers.
If you have not configured your z/OS environment for ICSF, see Cryptographic Services ICSF: System
Programmer's Guide for more information. To see whether ICSF has been started, check whether the started
task ICSF or CSF is active.
If you run Zowe high availability on a Sysplex, ICSF needs to be configured in a Sysplex environment to share
KDS data sets across systems in a Sysplex. For detailed information, see Running in a Sysplex Environment
The Zowe z/OS environment configuration JCL member ZWESECUR does not perform any steps related to
ICSF that is required for zssServer that the Zowe desktop uses. Therefore, if you want to use Zowe desktop,
you must perform the steps that are described in this section manually.
To generate symmetric keys, the ZWESVUSR user who runs Zowe server started task requires READ access
to CSFRNGL in the CSFSERV class.
Define or check the following configurations depending on whether ICSF is already installed:
The ICSF or CSF job that runs on your z/OS system.
The configuration of ICSF options in SYS1.PARMLIB(CSFPRM00) , SYS1.SAMPLIB ,
SYS1.PROCLIB .

Create CKDS, PKDS, TKDS VSAM data sets.

 Define and activate the CSFSERV class:
If you use RACF, issue the following commands:
If you use ACF2, issue the following commands (note that profile-prefix and profile-
suffix are user-defined):

(repeat for userids IKED, NSSD, and Policy Agent)

If you use Top Secret, issue the following command (note that profile-prefix and profile-
suffix are user defined):

(repeat for user-acids IKED, NSSD, and Policy Agent)

Notes:
Determine whether you want SAF authorization checks against CSFSERV and set
CSF.CSFSERV.AUTH.CSFRNG.DISABLE accordingly.

Refer to the z/OS 2.3.0 z/OS Cryptographic Services ICSF System Programmer's Guide: Installation,
initialization, and customization.
CCA and/or PKCS #11 coprocessor for random number generation.
Enable FACILITY IRR.PROGRAM.SIGNATURE.VERIFICATION and RDEFINE CSFINPV2 if
required.

Configure security environment switching

Typically, the user ZWESVUSR that the Zowe server started task runs under needs to be able to change the
security environment of its process to allow API requests to be issued on behalf of the logged on TSO user
ID, rather than the server's user ID. This capability provides the functionality that allows users to log on to the
Zowe desktop and use apps such as the File Editor to list data sets or USS files that the logged on user is
authorized to view and edit, rather than the user ID running the Zowe server. This technique is known as
impersonation.
To enable impersonation, you must grant the user ID ZWESVUSR associated with the Zowe server started
task UPDATE access to the BPX.SERVER and BPX.DAEMON profiles in the FACILITY class.
You can issue the following commands first to check whether you already have the impersonation profiles
defined as part of another server configuration, such as the FTPD daemon. Review the output to confirm
that the two impersonation profiles exist and the user ZWESVUSR who runs the Zowe server started task
has UPDATE access to both profiles.
If you use RACF, issue the following commands:
If you use Top Secret, issue the following commands:
If you use ACF2, issue the following commands:
If the user ZWESVUSR who runs the Zowe server started task does not have UPDATE access to both
profiles follow the instructions below.
If you use RACF, complete the following steps:
i. Activate and RACLIST the FACILITY class. This may have already been done on the z/OS
environment if another z/OS server has been previously configured to take advantage of the ability
to change its security environment, such as the FTPD daemon that is included with z/OS
Communications Server TCP/IP services.
ii. Define the impersonation profiles. This may have already been done on behalf of another server
such as the FTPD daemon.
iii. Having activated and RACLIST the FACILITY class, the user ID ZWESVUSR who runs the Zowe
server started task must be given update access to the BPX.SERVER and BPX.DAEMON profiles in
the FACILITY class.
where <zowe_stc_user> is ZWESVUSR unless a different user ID is being used for the z/OS
environment.
/ Activate these changes /
iv. Issue the following commands to check whether permission has been successfully granted:
If you use Top Secret, complete the following steps:
i. Define the BPX Resource and access for <zowe_stc_user>.
where <zowe_stc_user> is ZWESVUSR unless a different user ID is being used for the z/OS
environment.
 ii. Issue the following commands and review the output to check whether permission has been
successfully granted:
If you use ACF2, complete the following steps:
i. Define the BPX Resource and access for <zowe_stc_user>.
where <zowe_stc_user> is ZWESVUSR unless a different user ID is being used for the z/OS
environment.
ii. Issue the following commands and review the output to check whether permission has been
successfully granted:

Configure address space job naming

The user ID ZWESVUSR that is associated with the Zowe started task must have READ permission for the
BPX.JOBNAME profile in the FACILITY class. This is to allow setting of the names for the different z/OS
UNIX address spaces for the Zowe runtime components.
To display who is authorized to the profile, issue the following command:
Additionally, you need to activate facility class, permit BPX.JOBNAME , and refresh facility class:
For more information, see Setting up the UNIX-related FACILITY and SURROGAT class profiles in the "z/OS
UNIX System Services" documentation.

Configure multi-user address space (for TSS only)

The Zowe server started task ZWESLSTC is multi-user address space, and therefore a TSS FACILITY needs
to be defined and assigned to the started task. Then, all acids signing on to the started task will need to be
authorized to the FACILITY.
The following example shows how to create a new TSS FACILITY.
Example:
In the TSSPARMS, add the following lines to create the new FACILITY:
For more information about how to administer Facility Matrix Table, see How to Perform Facility Matrix Table
Administration.
To assign the FACILITY to the started task, issue the following command:
To authorize a user to sign on to the FACILITY, issues the following command:

Configure user IDs and groups for the Zowe started tasks
Zowe requires a user ID ZWESVUSR to execute its main z/OS runtime started task. This user ID must have a
valid OMVS segment.
Zowe requires a user ID ZWESIUSR to execute the cross memory server started task ZWESISTC . This
user ID must have a valid OMVS segment.
Zowe requires a group ZWEADMIN that both ZWESVUSR and ZWESIUSR should belong to. This group
must have a valid OMVS segment.
If you have run ZWESECUR , you do not need to perform the steps described in this section, because the
TSO commands to create the user IDs and groups are executed during the JCL sections of ZWESECUR .
If you have not run ZWESECUR and are manually creating the user ID and groups in your z/OS environment,
the commands are described below for reference.
To create the ZWEADMIN group, issue the following command:
To create the ZWESVUSR user ID for the main Zowe started task, issue the following command:
To create the ZWESIUSR group for the Zowe cross memory server started task, issue the following
command:

Configure ZWESLSTC to run Zowe high availability

instances under ZWESVUSR user ID
You need Zowe started task ZWESLSTC for Zowe high availability. When the Zowe started task ZWESLSTC
is started, it must be associated with the user ID ZWESVUSR and group ZWEADMIN . A different user ID and
group can be used if required to conform with existing naming standards.
If you have run ZWESECUR , you do not need to perform the steps described in this section, because they
are executed during the JCL section of ZWESECUR .
If you have not run ZWESECUR and are configuring your z/OS environment manually, the following steps
describe how to configure the started task ZWESLSTC to run under the correct user ID and group.
If you use RACF, issue the following commands:
If you use ACF2, issue the following commands:
If you use Top Secret, issue the following commands:

Configure the cross memory server for SAF

Zowe has a cross memory server that runs as an APF-authorized program with key 4 storage. Client
processes accessing the cross memory server's services must have READ access to a security profile
ZWES.IS in the FACILITY class. This authorization step is used to guard against access by non-
priviledged clients.
If you have run ZWESECUR you do not need to perform the steps described in this section.
If you have not run ZWESECUR and are configuring your z/OS environment manually, the following steps
describe how to configure the cross memory server for SAF.
Activate the FACILITY class, define a ZWES.IS profile, and grant READ access to the user ID ZWESVUSR .
This is the user ID that the main Zowe started task runs under.
To do this, issue the following commands that are also included in the ZWESECUR JCL member. The
commands assume that you run the Zowe server under the ZWESVUSR user.
If you use RACF, issue the following commands:
To see the current class settings, use:
To define and activate the FACILITY class, use:
To RACLIST the FACILITY class, use:
To define the ZWES.IS profile in the FACILITY class and grant Zowe's started task userid READ
access, issue the following commands:
 where <zowe_stc_user> is the user ID ZWESVUSR under which the Zowe server started task
runs.
To check whether the permission has been successfully granted, issue the following command:
This shows the user IDs who have access to the ZWES.IS class, which should include Zowe's
started task user ID with READ access.
If you use ACF2, issue the following commands:
If you use Top Secret, issue the following commands, where owner-acid can be IZUSVR or a
different ACID:
Notes:
The cross memory server treats "no decision" style SAF return codes as failures. If there is no covering
profile for the ZWES.IS resource in the FACILITY class, the request will be denied.
Cross memory server clients other than Zowe might have additional SAF security requirements. For
more information, see the documentation for the specific client.

Configure main Zowe server to use identity mapping

This security configuration is necessary for API ML to be able to map client certificate to a z/OS identity. A
user running API Gateway must have read access to the RACF general resource IRR.RUSERMAP in the
FACILITY class. To set up this security configuration, submit the ZWESECUR JCL member. For users
upgrading from version 1.18 and lower use the following configuration steps.
Using RACF
If you use RACF, verify and update permission in the FACILITY class.
Follow these steps:
. Verify user ZWESVUSR has read access.
. Add user ZWESVUSR permission to read.
. Activate changes.
Using ACF2
If you use ACF2, verify and update permission in the FACILITY class.
Follow these steps:
. Verify user ZWESVUSR has read access.
. Add user ZWESVUSR permission to read.
Using TSS
If you use TSS, verify and update permission in FACILITY class.
Follow these steps:
. verify user ZWESVUSR has read access.
. Add user ZWESVUSR permission to read.

Configure signed SAF Identity tokens (IDT)

This section provides a brief description of how to configure SAF Identity tokens on z/OS so that they can be
used by Zowe components like zss or API Mediation layer (Implement a new SAF IDT provider)
General steps are:
. Create PKCS#11 token
. Generate a secret key for the PKCS#11 token (you can use the sample program ZWESECKG in the
SZWESAMP dataset)
. Define a SAF resource profile under the IDTDATA SAF resource class
Details with examples can be found in documentation of external security products:
RACF - Signed and Unsigned Identity Tokens and IDT Configuration subsections in z/OS Security
Server RACROUTE Macro Reference book, link.
Top Secret - Maintain Identity Token (IDT) Records subsection in Administrating chapter, link.
ACF2 - IDTDATA Profile Records subsection in Administrating chapter, link.
A part of the Signed SAF Identity token configuration is a nontrivial step that has to generate a secret key for
the PKCS#11 token. The secret key is generated in ICSF by calling the PKCS#11 Generate Secret Key
(CSFPGSK) or Token Record Create (CSFPTRC) callable services. An example of the CSFPGSK callable
service can be found in the SZWESAMP dataset as the ZWESECKG job.
Granting users permission to access z/OSMF
Version: v2.0.x LTS

For every TSO user ID that is going to log on to Zowe and use services that require z/OSMF, it must have
permission to access the z/OSMF services that are used by Zowe. They should be added to the group with
appropriate z/OSMF privileges, IZUUSER or IZUADMIN by default.
This step is not included in the provided Zowe JCL because it must be done for every TSO user ID who
wants to access Zowe's z/OS services. The list of those user IDs will typically be the operators,
administrators, developers, or anyone else in the z/OS environment who is logging in to Zowe.
Note: You can skip this section if you use Zowe without z/OSMF. Zowe can operate without z/OSMF but
services that use z/OSMF REST APIs will not be available, specifically the USS, MVS, and JES Explorers and
the Zowe Command Line Interface files, jobs, workflows, tso, and console groups.
To grant permissions to the user ID to access z/OSMF,
If you use RACF, issue the following command:
If you use ACF2, issue the following commands:
If you use Top Secret, issue the following commands:
APF authorize load libraries
Version: v2.0.x LTS

Learn how to perform APF authorization of Zowe load libraries that require access to make privileged calls.
Zowe contains load modules that require access to make privileged z/OS security manager calls. These are
held in two load libraries which must be APF authorized. The command zwe init apfauth will read the
PDS names for the load libraries from zowe.yaml and perform the APF authority commands.
zowe.setup.dataset.authLoadLib specifies the user custom load library, containing the
ZWELNCH , ZWESIS01 and ZWESAUX load modules. These are the Zowe launcher, the ZIS cross
memory server and the auxiliary server.
zowe.setup.dataset.authPluginLib which references the load library for ZIS plugins.

Here is an example of running zwe init apfauth :

Specify --security-dry-run to have the command echo the commands that need to be run without
them being executed.
Configuring PKCS12 certificates
Version: v2.0.x LTS

Zowe is able to use PKCS12 certificates that are stored in USS. This certificate is used for encrypting TLS
communication between Zowe clients and the Zowe z/OS servers, as well as intra z/OS Zowe server to Zowe
server. Zowe uses a keystore directory to contain its external certificate, and a truststore directory
to hold the public keys of servers it communicate with (for example z/OSMF).
Using USS PKCS12 certificates is useful for proof of concept projects using a self signed certificates. For
production usage of Zowe it is recomended to work with certificates held in z/OS keystores. Working with
z/OS keystores may require system administrator priviledges and working with your z/OS security team, so
the self signed PKCS12 path is provided to assist with configuring and launching test and scratch Zowe
instances.

Use a PKCS12 certificate

When Zowe is launched details for the PKCS12 certificate used are specified in the zowe.yaml section
certificates . This contains information for the certificate name and its location, together with the
truststore location.
The two most common scenario for using a PKCS12 certtificate are where you have been given an existing
certificate and wish to configure Zowe to use it, or else you do not have a certificate and wish to generate a
new one. The zwe init certificate command supports both scenarios. The input parameters that
control certificate configuration are specified in the section zowe.setup.certificates

Create a self signed PKCS12 certificate

The following zowe.yaml example will generate:
A PKCS12 certificate, specified in zowe.setup.certificate.type
A keystore directory /global/zowe/keystore specified in
zowe.setup.certificate.pkcs12.directory .

A certificate name (or alias) localhost specified in zowe.setup.certificate.pkcs12.name

A certificate authority name local_ca specified in
zowe.setup.certificate.certificate.pkcs12.caAlias .
To assist with updating zowe.yaml the values to generate a self signed PKCS12 certificate are included in
the section beginning # >>>> Certificate setup scenario 1 . Other certificate scenarios lower
down in the zowe.yaml file are commented out.
The zwe init certificate command will generate a certificate based on the zowe.yaml values in
the zowe.setup.certificate section. These certificate values used at runtime are referenced in the
zowe.yanl section zowe.certificates . Specify --update-config for the zwe command to
update the runtime zowe.certificates section to reference the generated certificate generated from
the zowe.setup.certificate .
The follow command output shows generation of a self signed PKCS12 certificate using the default values.
Some detailed output messages have been omitted, but the flow can be viewed that creates the CA, creates
the keystore and adds the CA to it, create the certificate and adds that to the keystore, creates the
truststore, changes directory permissions to restrict access to the private key.
Because --update-config was specified the zowe.certificates section's values are updated to
reference the newly generated certificate. These updates are logged by the zwe init certificate
command output. Open the zowe.yaml file to check the references to the newly generated certificate
values, as shown below:
When using a self-signed certificate, you will be challenged by your browser when logging in to Zowe to
accept its untrusted certificate authority. Depending on the browser you are using there are different ways to
proceed.
Manually import a certificate authority into a web browser
To avoid the browser untrusted CA challenge, you can import Zowe's certificates into the browser to avoid
untrusted network traffic challenges. For more information, see Import the local CA certificate to your
browser.
To avoid requiring each browser to trust the CA that signed the Zowe certificate, you can use a public
certificate authority such as Symantec, Comodo, Let's Encrypt, or _GoDaddy_to create a certificate. These
certificates are trusted by all browsers and most REST API clients. This option, however, requires a manual
process to request a certificate and may incur a cost payable to the publicly trusted CA.
Configuring JCERACFS certificates in a key
Version: v2.0.x LTS

ring
Zowe is able to work with certificates held in a z/OS Keyring.
The JCL member .SZWESAMP(ZWEKRING) contains the security commands to create a keyring named
` ZoweKeyring and manage the certificate and certificate authoritie (CA) used by Zowe's servers to
encrypt TLS communications. The JCL contains commands for three z/OS security managers: RACF,
TopSecret, and ACF/2.
There are two ways to configure and submit ZWEKRING .
Customize and submit the ZWEKRING JCL member.
Customize the zowe.setup.certificate section in zowe.yaml and use the zwe init
certificate command.

If you use the zwe init certificate command this will prepare a customized JCL member using
ZWEKRING as a template.

A number of keytring scenarios are supported

Creation of a local certificate authority (CA) which is used to sign a locally generated certificate, both of
which are placed into the ZoweKeyring .
Importing an existing certificate already held in z/OS to the ZoweKeyring for use by Zowe.
Creation of a locally generated certificated and signing it with an existing certificate authority, and
placing the certificate into the key ring.
Create a certificate authority and use it to self sign a certificate
The zwe init security command takes its input from the zowe.setup.security section in
zowe.yaml . To help with customizing the file there are five sections in the file

Create a self signed JCERACFKS certificate

The following zowe.yaml example will generate:
 A JCERACFKS certificate, specified in zowe.setup.certificate.type
A keyring named ZoweKeyring specified in zowe.setup.certificate.keyring.name .
A certificate with the label localhost specified in zowe.setup.certificate.keyring.label
A certificate authority with the label localca specified in
zowe.setup.certificate.keyring.caLabel with a common name Zowe Service CA .

The follow command output shows generation of a self signed JCERACFKS certificate using the default
values. Some detailed output messages have been omitted.
When the command is run a customized JCL member name in created the CUST.JCLLIB data set. The
PDS name is defined in the zowe.setup.dataset.jcllib property. In the sample below the PDS
meember WINCHJ.ZWEV2.CUST.JCLLIB(ZW101431) is created that contains the security manager
commands and then submitted as a job ID ZWEKRING(JOB03054) .
Even though the job ends with code 0 there may be failures in the individual steps. It is advised to check the
job output. The security manager commands in the job will be generated based on the value of
zowe.security.product , and the job steps for each product are broken apart by security manager.

Because the --update-config parmarater was specified the runtime configuration section of
zowe.yaml is updated to match the values to the generated keystore, certificate, and certificate authority.
Set up Zowe certificates using workflows
Version: v2.0.x LTS

Zowe uses certificates that are held in z/OS Keyring.

You can use four z/OSMF workflows that enable you to manage keyring setup, certificates, certificate sign
requests and signatures, and load certificates to a keyring. Use the following workflows to set up certificates
for Zowe in your environment:
. Set up a Zowe certificate and keyring using ZWEKRING.xml
The ZWEKRING.xml workflow sets up a Zowe certificate and keyring. The workflow helps you set up
the certificate and keyring and has the following features:
Generates a Zowe certificate that is signed by the Zowe local CA
Imports an existing certificate that is held in z/OS to the keyring for Zowe
Imports an external Zowe certificate from a data set in PKCS12 format
Connects a z/OSMF certificate authority to the Zowe keyring
The workflow includes the steps that you can see on the following image:

Based on the variable setup from the first step, the workflow can perform various certificate
configurations and connect certificates to a keyring in RACF, TSS, and ACF2 security systems.
. Create a certificate sign request (CSR) using ZWECRECR.xml
The ZWECRECR.xml workflow creates a CSR request and has the following features:
Based on a variable setup, generates a certificate sign request.
You must define variables.
A CSR request is stored into a data set. Then the data set is automatically converted into a USS file.
You must specify the USS file path.
The workflow includes the steps that you can see on the following image:
 Note: You can find links to the specific security systems (BCM, IBM) official documentation in the
instructions section of the workflow in related steps.
. Sign a CSR request using ZWESIGNC.xml
The ZWESIGNC.xml workflow signs a CSR request.
After the successful workflow execution, the certificate is signed by the specified certificate authority
and is stored in USS.
The workflow includes the steps that you can see on the following image:

Fill in the fields, that you can see on the following image, to sign a CSR request. Ensure that the
workflow includes the following information:
A USS location path of the CSR file
A USS location path where a signed certificate is stored in pem format

. Load the Signed Client Authentication Certificate into ESM using ZWELOADC.xml
The ZWELOADC.xml workflow loads a signed client authentication certificate into a specific ESM
under your ACID.
The workflow can load ASCII- or EBCDIC-encoded certificate into a data set. Then, based on the
variable setup, the workflow loads the certificate into a specific ESM.
The workflow includes the steps that you can see on the following image:
Creating VSAM caching service datasets
Version: v2.0.x LTS

Zowe can work in a high availability (HA) configuration where multiple instances of the Zowe launcher are
started, either on the same LPAR or different LPARs connected through sysplex distributor. If you are only
running a single Zowe instance on a single LPAR you do not need to create a caching service so you may
skip this step.
In an HA setup the different Zowe API Mediation Gateway servers share the same northbound port (by
default 7554 ), and client traffic to this port is distributed between separate gateways that in turn dispatch
their work to different services. When any of the services individually become unavailable the work can be
routed to available services, which means that the initial northbound request will be fulfilled.
There are different storage methods that can be used as as the caching service for Zowe. One of these is
VSAM and this chapter describes how to create the data sets if you are using VSAM as your caching
service. If you are using another caching service such as redis or infinispan then you do not need to
create any VSAM files and you can skip the step described in this chapter. For more information on the
different caching services see Configuring the Caching Service for HA.

Using zwe init vsam command

The command zwe init vsam uses the template JCL in SZWESAMP(ZWECSVSM) . You can edit and
submit this yourself, or else if use zwe init vsam which will copy the source template member from
zowe.setup.mvs.hlq.SZWESAMP(ZWECVCSM) and create a target JCL member in
zowe.setup.mvs.jcllib(ZWECVSCM) with values extracted from the zowe.yaml file.

zowe.components.caching-service.storage.vsam.name variable

This is the data set name that the ZWECSVSM JCL will create. This is used to replace all occurrences of
#dsname in the ZWECSVSM data set.

Note: The ZWECSVSM JCL defines the key length and record length of the VSAM instance. If the key
length and record length of this JCL is changed,
zowe.environments.CACHING_STORAGE_VSAM_KEYLENGTH and
zowe.environments.CACHING_STORAGE_VSAM_RECORDLENGTH must be set to the new values.

zowe.components.caching-service.storage.mode variable
 This specifies whether you would like to use Record Level Sharing (RLS) for your VSAM data set. RLS
is recommended for Sysplex deployment. NONRLS is also an allowed value.
zowe.setup.vsam.storageClass variable

If you use the RLS mode, a storage class is required.

zowe.setup.vsam.volume variable

If you set to use the NONRLS mode, a storage volume is required.

If you want to preview the member before submitting it use the value --security-dry-run , otherwise
the command will submit the JCL and wait for its completion.
Installing Zowe main started tasks
Version: v2.0.x LTS

The JCL members for each of Zowe's started tasks need to be present on the JES proclib concatenation
path. The command zwe init stc will copy these from the install source location .SZWESAMP to the
targted PDS specified in the zowe.setup.dataset.proclib value USER.PROCLIB . The three proclib
member names are specified in zowe.yaml arguments.
The zwe init stc command uses the CUST.JCL LIB data sets as a staging area to contain
intermediatory JCL which are transformed version of the originals that are shiped in .SZWESAMP with
paths, PDS locations, and other runtime data updated. If you wish to just generate the CUST.JCLLIB
members without having them copied to USER.PROCLIB , specify --security-dry-run . If the JCL
members are already in the target PROCLIB, specify --allow-overwritten .
Here is an example:
Installing and configuring the Zowe cross
Version: v2.0.x LTS

memory server (ZWESISTC)

The Zowe cross memory server, also known as ZIS, provides privileged cross-memory services to the Zowe
Desktop and runs as an APF-authorized program. The same cross memory server can be used by multiple
Zowe desktops. The cross memory server is needed to be able to log on to the Zowe desktop and operate
its apps such as the File Editor. If you wish to start Zowe without the desktop (for example bring up just the
API Mediation Layer), you do not need to install and configure a cross memory server and can skip this step.
To install and configure the cross memory server, you must define APF-authorized load libraries, program
properties table (PPT) entries, and a parmlib. This requires familiarity with z/OS.
PDS sample library and PDSE load library
Load module
APF authorize
Key 4 non-swappable
PARMLIB
PROCLIB
SAF configuration
Summary of cross memory server installation
Starting and stopping the cross memory server on z/OS
Zowe auxiliary service
When to configure the auxiliary service
Installing the auxiliary service

PDS sample library and PDSE load library

The cross memory server runtime artifacts, the JCL for the started tasks, the parmlib, and members
containing sample configuration commands are found in the SZWESAMP PDS sample library.
The load modules for the cross memory server and an auxiliary server it uses are found in the SZWEAUTH
PDSE.
 Convenience Build The location of SZWESAMP and SZWEAUTH for a convenience build depends on
the value of the zowe.setup.dataset.prefix parameters in the zowe.yaml file used to
configure the zwe install command, see Install the MVS data sets.
SMP/E For an SMP/E installation, SZWESAMP and SZWEAUTH are the SMP/E target libraries whose
location depends on the value of the #thlq placeholder in the sample member
AZWE001.F1(ZWE3ALOC) .

The cross memory server is a long running server process that, by default, runs under the started task name
ZWESISTC with the user ID ZWESIUSR and group of ZWEADMIN .

The ZWESISTC started task serves the Zowe desktop that is running under the ZWESLSTC started task,
and provides it with secure services that require elevated privileges, such as supervisor state, system key, or
APF-authorization.
The user ID ZWESIUSR that is assigned to the cross memory server started tasks must have a valid OMVS
segment and read access to the load library SZWEAUTH and PARMLIB data sets. The cross memory server
loads some functions to LPA for its PC-cp services.
To install the cross memory server, enable the PROCLIB, PARMLIB, and load module. This topic describes
the steps to do this manually.

Load module
The cross memory server load module ZWESIS00 is installed by Zowe into a PDSE SZWEAUTH . For the
cross memory server to be started, the load module needs to be APF-authorized and the program needs to
run in key(4) as non-swappable.
APF authorize
APF authorize the PDSE SZWESAUTH . This allows the SMP/E APPLY and RESTORE jobs used for applying
maintenance to be operating on the runtime PDSE itself when PTF maintenance is applied.
Do not add the SZWEAUTH data set to the system LNKLIST or LPALST concatenations.
To check whether a load library is APF-authorized, you can issue the following command:
where the value of DSNAME is the name of the SZWEAUTH data set as created during Zowe installation that
contains the ZWESIS01 load module.
Issue one of the following operator commands to dynamically add the load library to the APF list (until next
IPL), where the value of DSNAME is the name of the SZWEAUTH data set, as created during Zowe
installation.
If the load library is not SMS-managed, issue the following operator command, where volser is the
name of the volume that holds the data set:
If the load library is SMS-managed, issue the following operator command:
Configuring using zwe init apfauth
If you are using the zwe init command to configure your z/OS system, the step zwe init apfauth
can be used to generate the SETPROG commands and execute them directly. This takes the input
parameters zowe.setup.mvs.authLoadLib for the SZWEAUTH PDS location, and
zowe.setup.mvs.authPluginLib for the location of the PDS that is used to contain plugins for the
cross memory server. For more information on zwe init apfauth see, APF Authorize Load Libraries.
Making APF auth be part of the IPL
Add one of the following lines to your active PROGxx PARMLIB member, for example
SYS1.PARMLIB(PROG00) , to ensure that the APF authorization is added automatically after next IPL. The
value of DSNAME is the name of the SZWEAUTH data set, as created during Zowe installation:
If the load library is not SMS-managed, add the following line, where volser is the name of the
volume that holds the data set:
If the load library is SMS-managed, add the following line:
The PDS member SZWESAMP(ZWESIMPRG) contains the SETPROG statement and PROGxx update for
reference.
Key 4 non-swappable
The cross memory server load module ZWESIS01 must run in key 4 and be non-swappable. For the server
to start in this environment, add the following PPT entries for the server and address spaces to the SCHEDxx
member of the system PARMLIB.
The PDS member SZWESAMP(ZWESISCH) contains the PPT lines for reference.
Then, issue the following command to make the SCHEDxx changes effective:

PARMLIB
The ZWESISTC started task must find a valid ZWESIPxx PARMLIB member in order to be launched
successfully. The SZWESAMP PDS created at installation time contains the member ZWESIP00 with
default configuration values. You can copy this member to another data set, for example your system
PARMLIB data set, or else leave it in SZWESAMP .
If you choose to leave ZWESIPxx in the installation PDS SZWESAMP used at installation time, this has
advantages for SMP/E maintenance because the APPLY and RESTORE jobs will be working directly against
the runtime library.
Wherever you place the ZWESIP00 member, ensure that the data set is listed in the PARMLIB DD
statement of the started task ZWESISTC .

PROCLIB
For the cross memory server to be started, you must move the JCL PROCLIB ZWESISTC member from the
installation PDS SAMPLIB SZWESAMP into a PDS that is on the JES concatenation path.
You need to update the ZWESISTC member in the JES concatenation path with the location of the load
library that contains the load module ZWESIS01 by editing the STEPLIB DD statement of ZWESISTC . Edit
the PARMLIB DD statement to point to the location of the PDS that contains the ZWESIP00 member.
For example, the sample JCL below shows ZWESISTC where the APF-authorized PDSE containing
ZWESIS01 is IBMUSER.ZWEV2.SZWEAUTH(ZWESIS01) and the PDS PARMLIB containing ZWESIP00 is
IBMUSER.ZWEV2.SZWESAMP(ZWESIP00) .

SAF configuration
Because the ZIS server makes z/OS security calls it restrits which clients are able to use it services, by
requiring them to have READ access to a security profile ZWES.IS in the FACILITY class.
The Zowe launcher started task ZWESLSTC needs to be able to access the ZIS server, which requires that
the user ID ZWESVUSR has access to ZWES.IS . The steps to do this are desribed in Configure the cross
memory server for SAF.

Summary of cross memory server installation

You can start the cross memory server using the command /S ZWESISTC once the following steps have
been completed.
JCL member ZWESVSTC is copied from SZWESAMP installation PDS to a PDS on the JES
concatenation path.
The PDSE Load Library SZWEAUTH is APF-authorized, or Load module ZWESI00 is copied to an
existing APF Auth LoadLib.
The JCL member ZWESVSTC DD statements are updated to point to the location of ZWESI00 and
ZWESIP00 .

The load module ZWESI00 must run in key 4 and be non-swappable by adding a PPT entry to the
SCHEDxx member of the system PARMLIB PPT PGMNAME(ZWESI00) KEY(4) NOSWAP .

Starting and stopping the cross memory server on z/OS

The cross memory server is run as a started task from the JCL in the PROCLIB member ZWESISTC . It
supports reusable address spaces and can be started through SDSF with the operator start command with
the REUSASID=YES keyword:
The ZWESISTC task starts and stops the ZWESASTC task as needed. Do not start the ZWESASTC task
manually.
To end the Zowe cross memory server process, issue the operator stop command through SDSF:
Note:
The starting and stopping of the ZWESVSTC started task for the main Zowe servers is independent of the
ZWESISTC cross memory server, which is an angel process. If you are running more than one ZWESVSTC
instance on the same LPAR, then these will be sharing the same ZWESISTC cross memory server. Stopping
ZWESISTC will affect the behavior of all Zowe servers on the same LPAR that use the same cross-memory
server name, for example ZWESIS_STD. The Zowe Cross Memory Server is designed to be a long-lived
address space. There is no requirement to recycle regularly. When the cross-memory server is started with a
new version of its load module, it abandons its current load module instance in LPA and loads the updated
version.
To diagnose problems that may occur with the Zowe ZWESVSTC not being able to attach to the
ZWESISTC cross memory server, a log file zssServer-yyyy-mm-dd-hh-mm.log is created in the log
directory each time ZIS is started. More details on diagnosing errors can be found in Zowe Application
Framework issues.

Zowe auxiliary service

Under some situations in support of a Zowe extension, the cross memory server will start, control, and stop
an auxiliary address space. This run as a ZWESASTC started task that runs the load module ZWESAUX .
When to configure the auxiliary service
Under normal Zowe operation, you will not see any auxiliary address spaces started. However, if you have
installed a vendor product running on top of Zowe, this may use the auxiliary service so it should be
configured to be launchable. A vendor product documentation will specify whether it needs the Zowe
auxiliary service to be configured so ensure that it is needed before attempting the configuration steps.
If you are just using core Zowe functionality, you do not need to configure the auxiliary service. Even with the
Zowe auxiliary service configured, there is no situation under which you should manually start the
ZWESASTC started task.

Installing the auxiliary service

To install the auxiliary service to allow it to run, you take similar steps to install and configure the cross
memory server as described above, but with a different JCL PROBLIC member and a different load module.
There is no PARMLIB for the auxiliary service.
JCL member ZWESASTC is copied from SZWESAMP installation PDS to a PDS on the JES
concatenation path.
The PDSE load library SZWEAUTH is APF-authorized, or load module ZWESAUX is copied to an existing
APF Auth LoadLib.
The load module ZWESAUX must run in key 4 and be non-swappable by adding a PPT entry to the
SCHEDxx member of the system PARMLIB PPT PGMNAME(ZWESAUX) KEY(4) NOSWAP .
Important!
The cross memory ZWESISTC task starts and stops the ZWESASTC task as needed. Do not start the
ZWESASTC task manually.
Zowe Auxiliary Address space
Version: v2.0.x LTS

The cross memory server runs as a started task ZWESISTC that uses the load module ZWESIS01 .
In some use cases, the Zowe cross memory server has to spawn child address spaces, which are known as
auxiliary (AUX) address spaces. The auxiliary address spaces run as the started task ZWESASTC using the
load module ZWESAUX and are started, controlled, and stopped by the cross memory server.
An example of when an auxiliary address space is used is for a system service that requires supervisor state
but cannot run in cross-memory mode. The service can be run in an AUX address space which is invoked by
the Cross Memory Server acting as a proxy for unauthorized users of the service.
Do not install the Zowe auxiliary address space unless a Zowe extension product's installation guide
explicitly asks for it to be done. This will occur if the extension product requires services of Zowe that cannot
be performed by the cross memory server and an auxiliary address space needs to be started.
A default installation of Zowe does not require auxiliary address spaces to be configured.
You do not start or stop the ZWESASTC manually.
Configure Zowe with z/OSMF Workflows
Version: v2.0.x LTS

As a system programmer, after you install Zowe, you can register and execute the z/OSMF workflows in the
web interface to complete the Zowe configuration. z/OSMF helps to simplify the Zowe configuration tasks
and reduce the level of expertise that is needed for Zowe configuration.
Ensure that you meet the following requirements before you start the Zowe configuration:
Install and configure z/OSMF
Install Zowe with an SMP/E build, PSWI, or a convenience build
You can complete the following tasks with the z/OSMF workflow:
Configure the Zowe instance directory
Enable the API ML gateway
Enable the metrics service
Enable the API catalog
Enable automatic discovery
Enable a caching service
Enable an application server
Enable the ZSS component
Enable the jobs API
Enable the files API
Enable JES Explorer
Enable MVS Explorer
Enable USS Explorer
You can execute the Zowe configuration workflow either from a PSWI during deployment or later from a
created software instance in z/OSMF. Alternatively, you can execute the configuration workflow z/OSMF
during the workflow registration process.

Configure the Zowe instance directory

The Zowe instance directory contains configuration data that is required to launch a Zowe runtime. This
includes port numbers, location of dependent runtime such as Java, Node, z/OSMF, as well as log files.
When Zowe is started, configuration data is read from files in the instance directory and logs will be written
to files in the instance directory. Zowe has three runtime systems: the z/OS Service microservice server, the
Zowe Application Server, and the Zowe API Mediation Layer microservices.
Register the ZWECONF.xml workflow definition file in the z/OSMF web interface to create a Zowe instance
directory and start the Zowe started task. The path to the workflow definition file is
<pathPrefix>/workflows/

After you register the workflow definition file, perform the following steps to complete the process:
. Define variables
The workflow includes the list of instance configuration and the Zowe variables. Enter the values for
variables based on your mainframe environment, Zowe instance configuration, and wanted
components.
. Create configuration
Execute the step to create a configuration zowe.yaml file with the variable setup that was defined in step
1.
. Run Zowe install
Execute the zwe install command with the previously stored zowe.yaml file as a parameter.
If you receive an error message (such as RC higher than 0), ensure that you edit incorrect input values
or system setup before you re-run the zwe install command. To overwrite changed output, edit
the step by adding the --allow-overwritten tag to the install command.
Example: Command that re-runs the installation
. Run Zowe init
Execute the zwe init command with the previously stored zowe.yaml file as a parameter.
Note: Messages and error codes from the subsequent JOBS command are not forwarded back to
z/OSMF.
 If you receive an error message (such as RC higher than 0) and want to find out the error cause, enter
ISPF and find corresponding subsequent JOBLOG.
If you execute the init step again, either manually delete failed artifacts that are created from previous
init steps, or edit the step by adding --allow-overwritten tag to the init command.
Example: Command that re-runs init
After you execute each step, the step is marked as Complete. After completing the workflow execution, you
can view the Zowe started task.

Register and execute workflow in the z/OSMF web

interface
z/OSMF workflow simplifies the procedure to configure and start Zowe. Execute the following steps to
register and execute the workflow in the z/OSMF web interface:
. Log in to the z/OSMF web interface and select Use Desktop Interface.
. Select the Workflows File.
. Select Create Workflow from the Actions menu.
The Create Workflow panel appears.
. Enter the complete USS path to the workflow you want to register in the Workflow Definition File field.
If you installed Zowe with the SMP/E build, the workflow is located in the SMP/E target zFS file
system that was mounted during the installation.
(Optional) Enter the complete USS path to the edited workflow properties file in the Workflow
Variable Input File field. Use this file to customize product instances and automate workflow
execution, saving time and effort when deploying multiple standardized Zowe instances. The
values from this file override the default values for the workflow variables.
The sample properties file is located in the same directory with the workflow definition file. Create a
copy of this file, and then modify as described in the file. Set the field to the path where the new file
is located.
 Note: If you use the convenience build, the workflows and variable input files are located in the
USS runtime folder in files/workflows.
. Select the System where the workflow runs.
. Select Next.
. Specify a unique Workflow name.
. Select or enter an Owner user ID, and select Assign all steps to owner user ID.
. Select Finish.
The workflow is registered in z/OSMF. The workflow is available for execution to deploy and configure
the Zowe instance.
. Execute the steps in order. Perform the following steps to execute each step individually:
a. Double-click the title of the step.
b. Select the Perform tab.
c. Review the step contents and update the input values as required.
d. Select Next.
Repeat the previous two steps to complete all items until the option Finish is available.
. Select Finish.
After you execute each step, the step is marked as Complete. The workflow is executed.
Overview
Version: v2.0.x LTS

Zowe has high availability feature built-in. This doc guides you through the configuration steps to enable this
feature.

Enable high availability when Zowe runs in Sysplex

Sysplex is required to make sure multiple Zowe instances can work together. Check Configuring Sysplex
for high availability for more details.
z/OSMF is an optional prerequisite of Zowe. If your Zowe instance works with z/OSMF, it's
recommended to configure z/OSMF for high availability in Sysplex.
The haInstances section must be defined in the Zowe YAML configuration. Check Zowe YAML
Configuration File Reference for more details.
Zowe caching service is required to convert stateful component to stateless component. Check
Configuring the Caching Service for HA for details.
Known limitations
To allow Sysplex Distributor to route traffic to the Gateway, you can only start one Gateway in each
LPAR within the Sysplex. All Gateways instances should be started on the same port configured on
Sysplex Distributor.
Zowe App Server should be accessed through the Gateway with a URL like https://<dvipa-
domain>:<external-port>/zlux/ui/v1 .

Enable high availability when Zowe runs in Kubernetes

If you deploy Zowe into Kubernetes, all components can also achieve high availability if you enable more
than one replicas for each component.
HorizontalPodAutoscaler is recommanded to let Kubernetes scales the component based on
workdload.
PodDisruptionBudget is recommended to let Kubernetes automatically handles disruptions like
upgrade.
Configuring Sysplex for high availability
Version: v2.0.x LTS

To deploy Zowe high availability, you must set up the Parallel Sysplex® environment. A Parallel Sysplex is a
collection of z/OS® systems that cooperatively use certain hardware and software components to achieve a
high-availability workload processing environment.

Sysplex environment requirements

Zowe high availability instances require a Sysplex environment that consists of the following:
One or more central processor complexes (CPCs) that can attach to a coupling facility
At least one coupling facility
At least one Sysplex timer
Connection to shared DASD
Shared SAF database, see Sharing a database with sysplex communication in data sharing mode
Sysplex Distributor with configured Dynamic VIPA TCP/IP address, see Configuring Sysplex Distributor
for instructions
VSAM record-level sharing (RLS), see Preparing for VSAM record-level sharing
USS Shared file system, see How to share file systems in a Sysplex
JESPlex/JES2 Multi-Access Spool (MAS) environment
z/OSMF high availability, see Configuring z/OSMF high availability in Sysplex
Node.js v12.x, v14.x (except v14.17.2), or v16.x
Note: It is highly recommended that Node.js installed on a shared file system.

Configuring Sysplex Distributor

The following example DVIPA configuration ensures the availability of Zowe in Hot-Standby mode. For
example, suppose that you have a Sysplex of two z/OS systems: A, B.
. Enable dynamic XCF on each host by adding the following TCP/IP definitions:
IPCONFIG SYSPLEXROUTING DYNAMICXCF x.x.x.A 255.255.255.0 1 for SYSA

IPCONFIG SYSPLEXROUTING DYNAMICXCF x.x.x.B 255.255.255.0 1 for SYSB

. Define a DVIPA for both systems:

where,
x.x.x.A is the home address for SYSA.
x.x.x.B is the home address for SYSB.
x.x.x.V is Dynamic VIP Address.
7554 is the port number of you Zowe API Mediation Layer Gateway. This should be the same port
number you configured for zowe.externalPort in zowe.yaml . See Updating the zowe.yaml
configuration file to learn more about zowe.yaml .
The VIPADISTRIBUTE statement with PREFERRED and BACKUP settings is used to enable automatic
dynamic VIPA takeover to occur, if needed.
All Zowe instances are bound to the DVIPA x.x.x.V. With both z/OS systems active in the Sysplex, the
preferred Zowe instance, SYSA receives all new incoming requests. If SYSA fails, new work requests to Zowe
are routed to the server on SYSB. When SYSA resumes normal operations, new work requests for Zowe are
routed to SYSA again. This is the default behavior because the AUTOSWITCHBACK parameter of the
VIPADISTRIBUTE statement is in effect by default.

If you do not want the distributor to switch back to the preferred target when it becomes available, you can
specify the NOAUTOSWITCHBACK parameter for the VIPADISTRIBUTE statement.
Configuring z/OSMF for high availability in
Version: v2.0.x LTS

Sysplex
z/OSMF high availability (HA) should be configured in Hot Standby mode to ensure availability of REST
services. The goal of this configuration is to ensure that one z/OSMF server is always available to provide the
REST services.
In Hot Standby mode, there is at least one backup (hot-standby) server and a preferred target server. Both
targets are active, and both z/OSMF servers are bound to the DVIPA. The preferred z/OSMF server receives
all new incoming requests. When the preferred z/OSMF server fails or the system becomes down, new
requests are routed to the backup (hot-standby) server. The distributing DVIPA does not perform load
balancing of requests across multiple systems. For more information, read the following articles in IBM
Documentation:
Configuring z/OSMF for availability
Configuring z/OSMF for high availability

Sysplex environment requirements

Before you begin, ensure that the Sysplex environment meets the following requirements for z/OSMF REST
services:
Shared SAF database. See Sharing a database with sysplex communication in data sharing mode in IBM
Documentation.
USS Shared file system. See How to share file systems in a Sysplex in IBM Documentation.
JESPlex/JES2 Multi-Access Spool (MAS) environment
Sysplex distributor, configured Dynamic VIPA TCP/IP address
Extended MCS console (EMCS)

Setting up z/OSMF nucleus

This information is intended for a first-time z/OSMF setup. Follow these high-level steps to create a
z/OSMF nucleus on your system.
For detailed information about each step, see Create a z/OSMF nucleus on your system in IBM
Documentation.
. Create the z/OSMF security authorizations by running the sample JCL SYS1.SAMPLIB(IZUSEC).
z/OSMF security authorizations will be used by all z/OSMF servers across multiple systems.
. Create a shared file system per z/OSMF server by running the sample JCL SYS1.SAMPLIB(IZUMKFS).
It holds configuration settings and the persistence data.
. Copy the Sample Parmlib Member SYS1.SAMPLIB(IZUPRM00) to PARMLIB and modify it according to
requirements of z/OSMF HA parmlib member in Sysplex. Each system uses a different IZUPRMxx
member. For example, IZUPRM0A and IZUPRM0B.
. Copy the following z/OSMF procedures from SYS1.PROCLIB into your JES concatenation:
IZUSVR1 (Each z/OSMF server should use the different started procedure. For example, IZUSVRA
and IZUSVRB.)
IZUANG1
IZUFPROC
. Define different STARTED profiles for z/OSMF servers.
Requirements of z/OSMF HA parmlib member in Sysplex
AUTOSTART_GROUP, more than one z/OSMF server (independent z/OSMF instances) is to be
autostarted in a Sysplex. For instance, System A will autostart a server and similarly, System B will
autostart the second z/OSMF server.
z/OSMF has a default autostart group (IZUDFLT) which is used in monoplex or single z/OS image. To
have more z/OSMF servers autostarted in a Sysplex, you must associate each server and the systems it
serves with a unique autostart group name. For example, AUTOSTART_GROUP('IZUDFLA') for
System A and AUTOSTART_GROUP('IZUDFLB') for System B
AUTOSTART(LOCAL) should be used by all z/OSMF instances.
HOSTNAME, the DVIPA address will be used as the z/OSMF host name for all instances.
HTTP_SSL_PORT, all servers are listening on the same port.
KEYRING_NAME, all servers should use the same key ring such as IZUKeyring.IZUDFLT .
 SERVER_PROC, each z/OSMF server should use the different started procedure. For example, IZUSVRA
and IZUSVRB.
ANGEL_PROC, all z/OSMF servers can connect to the same z/OSMF angel process such as IZUANG1.
SAF_PREFIX, they should use the same SAF profile prefix such as IZUDFLT.
USER_DIR, each instance uses a shared file system with a unique mount point for each AUTOSTART
group that be automatically started. For example, /global/zosmf/zosmfa and
/global/zosmf/zosmfb .

Configuring z/OSMF for high availability

The following DVIPA configuration ensures the availability of z/OSMF for Hot-Standby. For example, suppose
that you have a Sysplex of two z/OS systems: A, B.
. Enable dynamic XCF on each host by adding the following TCP/IP definitions:
IPCONFIG SYSPLEXROUTING DYNAMICXCF x.x.x.A 255.255.255.0 1 for SYSA

IPCONFIG SYSPLEXROUTING DYNAMICXCF x.x.x.B 255.255.255.0 1 for SYSB

. Define a dynamic VIPA (DVIPA) for both systems:

where,
x.x.x.A is the home address for SYSA.
x.x.x.B is the home address for SYSB.
x.x.x.V is Dynamic VIP Address.

The VIPADISTRIBUTE statement with PREFERRED and BACKUP settings is used to enable automatic
dynamic VIPA takeover to occur, if needed.
Both z/OSMF servers are bound to the DVIPA x.x.x.V. With both z/OS systems active in the Sysplex, the
preferred z/OSMF server, SYSA receives all new incoming requests. If SYSA fails, new work requests for
z/OSMF are routed to the server on SYSB. When SYSA resumes normal operations, new work requests for
z/OSMF are routed to SYSA again. This is the default behavior because the AUTOSWITCHBACK parameter
of the VIPADISTRIBUTE statement is in effect by default.
If you do not want the distributor to switch back to the preferred target when it becomes available, you can
specify the NOAUTOSWITCHBACK parameter for the VIPADISTRIBUTE statement.
Configuring the Caching Service for HA
Version: v2.0.x LTS

Zowe uses the Caching Service to centralize the state data persistent in high availability (HA) mode. If you
are runnning the caching service on z/OS there are three storage methods: inMemory , infinispan or
VSAM . If you are running the caching service off platform, such as a linux or windows container image, it is
also possible to specify redis or infinispan .
To learn more about Caching Service, see Using the Caching Service.
For users
inMemory
This storage method is designed for quick start of the service and should be used only for single
instance scenario and development or test purpose. Do not use it in production or high availability
scenario.
To use this method, set the zowe.components.caching-service.storage.mode value to
inMemory in the zowe.yaml configuration file. When this method is enabled, the Caching Service
will not persist any data.
VSAM
To use this method,
i. Set the value of zowe.components.caching-service.storage.mode value to VSAM in the
zowe.yaml configuration file.

ii. Create a VSAM data set. See Initialize VSAM data set for instructions. There are two ways to create
the data set, either using the JCL member SZWESAMP(ZWECVSEM) where the data set name is
defined in the #dsname variable.
iii. In zowe.yaml , configure zowe.components.caching-sevice.storage.vsam.name with
the VSAM data set name. If in step 2 you used zwe init vsam to create the VSAM data set
then the values will already be set.
redis
Redis is not available if you are running the API Mediation Layer on z/OS under unix system services. Its
usage is for when the APIML is running off platform, such as in a linux or windows container as part of a
hybrid cloud deployment.
To enable this method, set the value of zowe.components.caching-service.storage.mode to
redis in the zowe.yaml configuration file. There are a number of values to control the redis nodes,
sentinel and ssl properties that will need to be set in the zowe.yaml file. For more information on
these properties and their values see Redis configuration.
infinispan
Infinispan is designed to be run mainly on z/OS since it offers good performance. To enable this
method, set the value of zowe.components.caching-service.storage.mode to infinispan
in the zowe.yaml configuration file. Infinispan environment variables are not currently following the v2
naming convention, so they must be defined into zowe.environments section. For more information
on these properties and their values see Infinispan configuration.
Starting and stopping Zowe
Version: v2.0.x LTS

Zowe consists 3 main started tasks:

ZWESLSTC as Zowe main started task,

ZWESISTC as Zowe cross memory server

and ZWESASTC as Zowe cross memory auxiliary server.

Starting and stopping the cross memory server ZWESISTC

on z/OS
The cross memory server is run as a started task from the JCL in the PROCLIB member ZWESISTC . It
supports reusable address spaces and can be started through SDSF with the operator start command with
the REUSASID=YES keyword:
The ZWESISTC task starts and stops the ZWESASTC task as needed. Do not start the ZWESASTC task
manually.
To end the Zowe cross memory server process, issue the operator stop command through SDSF:
Note:
The starting and stopping of the ZWESLSTC started task for the main Zowe servers is independent of the
ZWESISTC cross memory server, which is an angel process. If you are running more than one ZWESLSTC
instance on the same LPAR, then these will be sharing the same ZWESISTC cross memory server. Stopping
ZWESISTC will affect the behavior of all Zowe servers on the same LPAR that use the same cross-memory
server name, for example ZWESIS_STD . The Zowe Cross Memory Server is designed to be a long-lived
address space. There is no requirement to recycle regularly. When the cross-memory server is started with a
new version of its load module, it abandons its current load module instance in LPA and loads the updated
version.

Starting and stopping the cross memory auxiliary server

ZWESASTC on z/OS
This is handled automatically by Zowe cross memory server. You don't need to manually start or stop this
started task.

Starting and stopping Zowe main server ZWESLSTC on z/OS

with zwe server command
Zowe ships zwe start and zwe stop commands to help you start and stop Zowe main server.
To start Zowe, run zwe start --config /path/to/my/zowe.yaml command. It will issue S
command to Zowe ZWESLSTC .
Here is an example:
Job name ZWE1SV can be customized with zowe.job.name in your Zowe configuration file.
You can use zwe start command to start a Zowe high availability instance defined on other LPAR within
the Sysplex. For example, zwe start --config /path/to/my/zowe.yaml --ha-instance
hainst2 . This requires these information be defined in Zowe configuration file:

zwe start command will use ROUTE command to send S ZWESLSTC command to LPAR2 system.

To stop Zowe, run zwe stop --config /path/to/my/zowe.yaml command. It will issue P
command to Zowe job.
Here is an example:

Starting and stopping Zowe main server ZWESLSTC on z/OS

manually
To start Zowe main server, you can issue S ZWESLSTC command. Same as normal JES S command, you
can customize JOBNAME . For example, S ZWESLSTC,JOBNAME=ZWE1SV .
If you have Zowe high availability instance defined and want to start a specific HA instance, for example
myinst1 , you can pass with HAINST parameter. Here is an example: S
ZWESLSTC,HAINST=myinst1,JOBNAME=ZWE1SV1 . Zowe high availability instance name is case
insensitive. HAINST=myinst1 and HAINST=MYINST1 are same.
If you are starting Zowe high availability instance for another LPAR in the Sysplex, you can use ROUTE
command to route the S command to the target system. For example, I'm working on SYSNAME LPAR1
and want to start HA instance myinst2 on LPAR2 , you can issue RO LPAR2,S
ZWESLSTC,HAINST=myinst2,JOBNAME=ZWE1SV2 .

To stop Zowe main server, you can issue P <jobname> command.

CAUTION
With Zowe version 1, you can issue C command to stop Zowe main server. This is not supported in
version 2 anymore. A P command is required to make sure Zowe components can be shuted down
properly.

Stopping and starting a Zowe component without restarting

Zowe main server
You can restart a Zowe component with JES modify command without restarting the whole Zowe main
server. You need to know these information before issuing the modify command:
Your Zowe main server job name. By default, it is configured as ZWE1SV . You can find your customized
value by checking zowe.job.name defined in Zowe configuration file.
The component name you want to stop or start. You can find a full list of installed components by listing
<RUNTIME>/components directory and Zowe extension directory.

To stop a running Zowe component, issue F <zowe-job>,APPL=STOP(<component-name>) command.

For example, if you want to stop app-server , issue F ZWE1SV,APPL=STOP(app-server) .
To start a stopped Zowe component, issue F <zowe-job>,APPL=START(<component-name>)
command. For example, if you want to start app-server , issue F ZWE1SV,APPL=START(app-
server) .

Note, please be aware that not all components can be restarted with this method. Some components may
rely on another and you may need to restart affected components as well.
Verifying Zowe installation on z/OS
Version: v2.0.x LTS

After the Zowe™ started task ZWESLSTC is running, follow the instructions in the following sections to
verify that the components are functional.
Verifying Zowe Application Framework installation
Verifying API Mediation installation
Verifying z/OS Services installation
Note: Not all components may have been started. Which components have been started depends on your
setting of the component enabled status in Zowe configuration file (usually zowe.yaml ). If you set
enabled to be true for gateway , discovery and api-catalog , the API Mediation Layer and
z/OS Services are started. If you set enabled to be true for app-server and zss , the Zowe
Application Framework (also known as Zowe desktop) are started. Those using containerization may only
have ZSS started. For more information, see reference of YAML configurations - components.

Verifying Zowe Application Framework installation

If the Zowe Application Framework is installed correctly, you can open the Zowe Desktop from a supported
browser.
From a supported browser, open the Zowe Desktop at https://myhost:httpsPort
where,
myHost is the host on which you installed the Zowe Application Server.
httpsPort is the port number value components.app-server.port in zowe.yaml . For more
information, see Configure component app-server.
For example, if the Zowe Application Server runs on host myhost and the port number that is assigned
to components.app-server.port is 12345, you specify https://myhost:12345 . The web
desktop uses page direct to the actual initial page which is
https://myhost:12345/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html . If the
redirect fails, try the full URL.
If the desktop appears but you are unable to log on, check Cannot log into the Zowe desktop for
troubleshooting tips.

Verifying API Mediation installation

Use your preferred REST API client to review the value of the status variable of the API Catalog service that
is routed through the API Gateway using the following URL:
where,
myHost is the host on which you installed the Zowe API Mediation Layer.
httpsPort is the port number value zowe.externalPort in zowe.yaml . For more information, see
Domain and port to access Zowe.
Example:
The following example illustrates how to use the curl utility to invoke API Mediation Layer endpoint and the
grep utility to parse out the response status variable value
The response UP confirms that API Mediation Layer is installed and is running properly.

Verifying z/OS Services installation

Zowe z/OS services usually are registered with Zowe APIML Discovery and exposed with certain service url
like /<service>/api/v1 .
Here we give an example of verifying jobs-api shipped with Zowe. Please be aware that jobs-api is
not enabled by default if you created your Zowe configuration file from example-zowe.yaml . To enable
jobs-api , you need to set components.jobs-api.enabled to be true and restart Zowe. You can
verify the installation of jobs-api service from an internet browser by entering the following case-
sensitive URL:
where,
gatewayPort is the port number that is assigned to zowe.externalPort in the zowe.yaml file used
to launch Zowe. For more information, see Domain and port to access Zowe.
The above link should prompt you to login. After you input correct user name and password of your target
z/OS system, you should see JSON format data of all jobs running on the system.
Introduction
Version: v2.0.x LTS

Zowe (server) containers are available for download as an alternative to running Zowe servers on z/OS
through the Zowe convenience and SMP/E builds. You can choose the appropriate installation type for your
use case. There are several advantages of using containers wherein you can:
Run Zowe servers on other platforms including Linux on Z and your PC
Run Zowe servers local to your system for rapid development
Run redundant copies of servers for scaling capacity to meet workload requirements
Leverage container monitoring tools
If you are new to containers, you can learn about the concepts from the Kubernetes website.
The Zowe containers are designed to be run together with extensions and Zowe utilities and therefore are
built for orchestration software that can manage the relationship and lifecycle of the containers. The
following topics guide you to set up and use Zowe's containers with the Kubernetes orchestration software.
. Prerequisites
. Downloading and installing
. Configuring the Zowe container environment
. Starting, stopping, and monitoring
. Known limitations

Known limitations
You may encounter an issue that some plugins are not showing up in Zowe Desktop. You can try
Refresh Applications icon showing up in Desktop start menu.

You may encounter an issue that some services are not showing up in Zowe API Catalog. You can try
Refresh Static APIs button showing up in top-right corner of API Catalog web page.
Prerequisites
Version: v2.0.x LTS

Before you install the Zowe server container, make sure that you have the required software and
environments.
Zowe installed on z/OS for users of ZSS and ZIS (default when you use the Zowe Application
Framework app-server , the Zowe Desktop, or products that are based on them)
z/OSMF installed on z/OS for users of it (default when you use gateway , API Mediation Layer, Web
Explorers, or products that are based on them)
A container runtime, such as:
Docker
CRI-O
containerd
Kubernetes Cluster software
kubectl, for initial setup and management of the cluster
Note: This documentation uses container terminology that may be explained within the Kubernetes
Glossary.

Kubernetes cluster
The Zowe containerization solution is compatible with Kubernetes v1.19+ or OpenShift v4.6+.
You can prepare a Kubernetes cluster based on your requirements in many different ways.
For development purposes, you can set up a Kubernetes cluster on your local computer in one of the
following ways:
Enable Kubernetes shipped with Docker Desktop
Set up minikube
Attention! You must make sure that the Kubernetes cluster you have created has a minimum RAM of
3GB in order for Zowe to start.
 For production purposes, you can set up a Kubernetes cluster in one of the following ways:
Bootstrap your own cluster by following instructions in Installing Kubernetes with deployment tools
in the Kubernetes documentation.
Provision a Kubernetes cluster from popular Cloud vendors:
Amazon Elastic Kubernetes Service
Microsoft Azure Kubernetes Service
IBM Cloud Kubernetes Service
Google Cloud Kubernetes Engine

kubectl tool
You need kubectl CLI tool installed on your local computer where you want to manage the Kubernetes
cluster. For instructions on how to install the kubectl tool, see Install Tools in the Kubernetes documentation.
Downloading and installing
Version: v2.0.x LTS

Learn how to download and install Zowe's containers.

Downloading
You can download Zowe's containers in one of the following ways:
Downloading configuration samples
Downloading container images
Downloading configuration samples
The easiest way to install and run Zowe's containers is by using the configuration samples that are provided
on Zowe's website. If you don't already have these samples, you can download them by completing the
following tasks:
. Download Zowe containerization build from zowe.org.
. Extract the compressed file to the system where you will run the Zowe containers.
. Find the samples within the extracted folder kubernetes .
Downloading container images
Downloading Zowe's container images manually is not required because this can be done automatically
when applying a Kubernetes deployment configuration.
If wanted, you can download Zowe's container images manually by using the docker pull commands.
This allows you to get an image from a registry or attach an image that you have downloaded directly. You
can find Zowe's container images in https://zowe.jfrog.io/ui/repos/tree/General/docker-release%2Fompzowe:
Registry: zowe-docker-release.jfrog.io
Organization: ompzowe
Full image addresses include,
zowe-docker-release.jfrog.io/ompzowe/gateway-service:latest-ubuntu
 zowe-docker-release.jfrog.io/ompzowe/app-server:latest-ubuntu

zowe-docker-release.jfrog.io/ompzowe/explorer-jes:latest-ubuntu

Therefore, you can download these manually with the docker pull commands. For example,
docker pull zowe-docker-release.jfrog.io/ompzowe/app-server:latest-ubuntu

Installing
You do not need to install the Zowe containers if you use Zowe's Kubernetes configuration samples. By
default, these sample configurations will pull Zowe component images from the public Zowe docker release
registry zowe-docker-release.jfrog.io directly and then start them. Your Kubernetes nodes require
an Internet connection that can reach this registry.
An image could be considered "installed" when it is findable by Kubernetes. Just like downloading, this is
done automatically by Kubernetes but commands such as docker pull or docker load
accomplishes the same task.

Upgrading
Upgrade is an automatic process when you apply Kubernetes deployment configuration. The configuration
files tell Kubernetes to automatically download the latest version of Zowe. Here, latest is the keyword for
constantly updated version. For example zowe-docker-release.jfrog.io/ompzowe/gateway-
service:latest-ubuntu .

Note: Automatic upgrades can fail if you have changed the workload configuration files to use a specific
Zowe version. In that case, you must enter the latest version manually in the configuration file such as
zowe-docker-release.jfrog.io/ompzowe/gateway-service:2.0.0-ubuntu .

If your Kubernetes nodes do not have an Internet connection, you can follow the instruction of the previous
step to manually pull all images into all your Kubernetes nodes. After you have done this, you need to modify
all occurrences of imagePullPolicy: Always in the sample configurations and replace them with
imagePullPolicy: Never before applying them.
Configuring
Version: v2.0.x LTS

Zowe provides sample configurations that make it easy for you to run Zowe in Kubernetes. You can use them
directly or as a reference.
You can customize the configuration or make your own. If you do so, note the following objects that are
expected by the container deployments:
Kind Name Note
Namespace zowe
ServiceAccount zowe-sa

ConfigMap zowe- Contains zowe-certificates.env with the same

certificates-cm format as seen on z/OS keystore
zowe- Contains the base64 PEM and P12 data for keystore and
Secret certificates- truststore
secret

Ingress discovery- Used for external access to the Discovery service

ingress
Ingress gateway- Used for external access to the Gateway service
ingress
Route discovery Used for external access to the Discovery service
Route gateway Used for external access to the Gateway service

Service discovery- Used for internal or external access to the Discovery

service service

Service gateway- Used for external access to the Gateway service

service
 Kind Name Note

Service catalog- Used for access to the Catalog service

service
zowe-
PersistentVolumeClaim workspace-
pvc
HorizontalPodAutoscaler * Autoscalers exist for the various pods
PodDisruptionBudget * Disruption budgets exist for the various pods
To configure the Zowe container environment, complete the following procedure.

1. Create namespace and service account

Run the following commands to create Zowe's Namespace zowe with Service Account zowe-sa .
Note that by default, zowe-sa service account has automountServiceAccountToken disabled for
security purposes.
To verify, check the following configurations.
kubectl get namespaces should show a Namespace zowe .

This displays the default Namespace zowe, if not set.

kubectl get serviceaccounts --namespace zowe should show a ServiceAccount zowe-sa .

This displays the default ServiceAccount zowe-sa, if not set.

2. Create Persistent Volume Claim (PVC)

Zowe's PVC has a default StorageClass value that may not apply to all Kubernetes clusters. Check and
customize the storageClassName value of samples/workspace-pvc.yaml as needed. You can use
kubectl get sc to confirm which StorageClass you can use.
After you customize the storageClassName value, apply the result by issuing the following commands:
To verify, run the following commands and check if the STATUS of line item zowe-workspace-pvc
shows as Bound .
IMPORTANT, zowe-workspace-pvc PersistentVolumeClaim must be declared in access mode
ReadWriteMany to allow the workspace be shared by all Zowe components.

In some Kubernetes environment, you may need to define PeristentVolume and define volumeName
in PersistentVolumeClaim instead of defining storageClassName . Please consult your Kubernetes
administrator to confirm the appropriate way for your environment. This is an example to configure
PersistentVolumeClaim with pre-configured zowe-workspace-pv PeristentVolume .

3. Create and modify ConfigMaps and Secrets

Similarly, to running Zowe services on z/OS, you can use Zowe configuration file ( zowe.yaml ) to
customize Zowe in Kubernetes.
You can modify samples/config-cm.yaml , , and samples/certificates-secret.yaml directly.
Or more conveniently, if you have Zowe ZSS/ZIS running on z/OS, the Kubernetes environment can reuse
instance and keystore configuration from that installation.
If you want to manually create, or later customize the ConfigMaps and Secrets, see Customizing or manually
creating ConfigMaps and Secrets for details.
To create and modify ConfigMaps and Secrets by using the migrate configuration script, complete the
following steps:
a. On z/OS, run the following command:
This migration script supports these parameters:
--config or -c : Defines the path to your configuration file, usually referred as zowe.yaml .

--domains : Defines the domain list will be put into certificate Subject Alternative Name (SAN). This is
optional, default value is localhost .
--external-port : Defines the external port number to access APIML Gateway running in
Kubernetes. This is optional, default value is 7554 .
--k8s-namespace : Defines the Kubernetes namespace. This is optional, default value is zowe .
 --k8s-cluster-name : Defines the Kubernetes cluster name. This is optional, default value is
cluster.local .
--password : Defines password of the certificate keystore. This is optional, default value is
password .

--ca-alias : Defines the alias name of the certificate authority which is used to sign CSR. This is
optional, default value is local_ca . This argument is only used to sign a new certificate if the
migration script will re-generate new certificates for Kubernetes.
--ca-password : Defines the password of the certificate authority keystore which is used to sign
CSR. This is optional, default value is local_ca_password . This argument is only used if the
migration script will re-generate new certificates for Kubernetes.
--silent or -s is an optional parameter can help you suppress all standard output except for the
Kubernetes manifests will be generated.
As a result, it displays ConfigMaps zowe-config and Secrets ( zowe-certificates-secret )
Kubernetes objects which are based on the Zowe instance and keystore used. The content looks similar to
samples/config-cm.yaml , samples/certificates-cm.yaml and samples/certificates-
secret.yaml but with real values.

b. Follow the instructions in the script output to copy the output and save it as a YAML file configs.yaml
on your computer where you manage Kubernetes.
c. Apply the file into Kubernetes:
d. Remove the previously saved configs.yaml file from all systems for security.
To verify:
kubectl get configmaps --namespace zowe

This command must display the two ConfigMaps zowe-config and zowe-certificates-cm .
kubectl get secrets --namespace zowe

This command must display a Secret zowe-certificates-secret .

4. Expose API Mediation Layer components

This step makes Zowe's Gateway, Discovery, and API Catalog servers available over a network.
The Gateway is always required to be externally accessible, and depending upon your environment the
Discovery service may also need to be externally accessible.
The actions you need to take in this step vary depending upon your Kubernetes cluster configuration. If you
are uncertain about this section, please contact your Kubernetes administrator or the Zowe community.
4a. Create service
You can set up either a LoadBalancer or NodePort type Service.
Note: Because NodePort cannot be used together with NetworkPolicies , LoadBalancer and
Ingress is preferred configuration option.

Review the following table for steps you may take depending on the Kubernetes provider you use. If you
don't need additional setups, you can skip steps 4b, 4c and jump directly to the Apply zowe section.
Kubernetes Service Additional setups required
provider

minikube LoadBalancer or Port Forward (on next section Starting, stopping, and
NodePort monitoring)
docker-desktop LoadBalancer none
bare-metal LoadBalancer or Create Ingress
NodePort
cloud-vendors LoadBalancer none

OpenShift LoadBalancer or Create Route

NodePort
Defining api-catalog service
api-catalog-service is required by Zowe, but not necessarily exposed to external users. Therefore,
api-catalog-service is defined as type ClusterIP .

To define this service, run the command:

Upon success, you should see the following output:
Then, you can proceed with creating the Gateway and Discovery services according to your environment.
Applying Gateway Service
If using LoadBalancer , run the command:
Or if using NodePort instead, first check spec.ports[0].nodePort as this will be the port to be
exposed to external. In this case, the default gateway port is not 7554 but 32554. You will need to use
https://<your-k8s-node>:32554/ to access APIML Gateway. To apply NodePort type gateway-
service , run the following command:

To verify either case, run the following command and check that the command displays the service
gateway-service .

Applying Discovery service

Exposing the Discovery service is only required when there is a Zowe service or extension which needs to be
registered to the API Mediation Layer but is running outside of Kubernetes, such as on z/OS. Otherwise, the
discovery service can remain accessible only within the Kubernetes environment.
Optional: To setup the discovery service without exposing it externally, edit samples/discovery-
service-lb.yaml if using LoadBalancer type services, or samples/discovery-service-
np.yaml if using NodePort type services. In either file, specify ClusterIP as the type, replacing the
NodePort or LoadBalancer value.

To enable the service externally when using LoadBalancer services, run the command:
Or if using NodePort instead, first check spec.ports[0].nodePort as this will be the port to be
exposed to external. In this case, the default discovery port is not 7553 but 32553. And you will need to use
https://<your-k8s-node>:32553/ to access APIML Discovery. To apply NodePort type
discovery-service , run the following command:

To verify either case, run the following command and check that this command displays the service
discovery-service :

kubectl get services --namespace zowe

Upon completion of all the preceding steps in this a. Create service section, you may need to run additional
setups. Refer to "Additional setups required" in the table. If you don't need additional setups, you can skip
4b, 4c, 4d, and jump directly to Apply Zowe section.
4b. Create Ingress (Bare-metal)
An Ingress gives Services externally-reachable URLs and may provide other abilities such as traffic load
balancing.
To create Ingress, perform the following steps:
a. Edit samples/gateway-ingress.yaml and samples/discovery-ingress.yaml before applying
them, by uncommenting the lines (19 and 20) for defining spec.rules[0].host and http: , and then
commenting out the line below, - http:
b. Run the following commands:
To verify, run the following commands:
kubectl get ingresses --namespace zowe

This command must display two Ingresses gateway-ingress and discovery-ingress .

Upon completion, you can finish the setup by applying zowe and starting it.
4c. Create Route (OpenShift)
If you are using OpenShift and choose to use LoadBalancer services, you may already have an external
IP for the service. You can use that external IP to access Zowe APIML Gateway. To verify your service
external IP, run:
If you see an IP in the EXTERNAL-IP column, that means your OpenShift is properly configured and can
provision external IP for you. If you see <pending> and it does not change after waiting for a while, that
means you may not be able to use LoadBalancer services with your current configuration. Try
ClusterIP services and define Route . A Route is a way to expose a service by giving it an externally-
reachable hostname.
To create a route, perform the following steps:
a. Check and set the value of spec.port.targetPort in samples/gateway-route.yaml and
samples/discovery-route.yaml before applying the changes.

b. Run the following commands:

To verify, run the following commands:
oc get routes --namespace zowe

This command must display the two Services gateway and discovery .
Upon completion, you can finish the setup by applying zowe and starting it.

Customizing or manually creating ConfigMaps and

Secrets
The z/OS to k8s convert tool can automatically create a config map and secret. However, if you want to
customize or create your own, review the instructions in this section.
To make certificates work in Kubernetes, make sure the certificate you are using have defined the following
domains in certificate Subject Alt Name (SAN):
your external domains to access Zowe APIML Gateway Service running in Kubernetes cluster
*.<k8s-namespace>.svc.<k8s-cluster-name>

*.discovery-service.<k8s-namespace>.svc.<k8s-cluster-name>

*.gateway-service.<k8s-namespace>.svc.<k8s-cluster-name>

*.<k8s-namespace>.pod.<k8s-cluster-name>

<k8s-namespace> is the Kubernetes Namespace you installed Zowe into. And <k8s-cluster-name>
is the Kubernetes cluster name, which usually should be cluster.local .
Without the additional domains in SAN, you may see warnings/errors related to certificate validation.
If you cannot add those domains into certificate Subject Alt Name (SAN), you can change
zowe.verifyCertificates to NONSTRICT mode. Zowe components will not validate domain names
but will continue to validate certificate chain, validity and whether it's trusted in Zowe truststore.
CAUTION
 It's not recommended to disable zowe.verifyCertificates .
Notes: When the following conditions are true, this migration script will regenerate a new set of certificates
for you with proper domain names listed above.
You use zwe init command to initialize Zowe
You use PKCS#12 format keystore by defining zowe.setup.certificate.type: PKCS12
You did not define zowe.setup.certificate.pkcs12.import.keystore and let zwe
command to generate PKCS12 keystore for you
You enabled STRICT mode zowe.verifyCertificates
To manually create the ConfigMaps and Secrets used by Zowe containers, you must create the following
objects:
. A ConfigMap, with values based upon a Zowe configuration zowe.yaml and similar to the example
samples/config-cm.yaml with the following differences to the values seen on a z/OS installation:

zowe.setup and haInstances are not needed for Zowe running in Kubernetes and will be
ignored. You can remove them.
java.home and node.home are not usually needed if you are using Zowe base images.

zowe.runtimeDirectory must be set to /home/zowe/runtime .

zowe.externalDomains is suggested to define as a list of domains you are using to access

your Kubernetes cluster.
zowe.externalPort must be the port you expose to end-user. This value is optional if it's same
as default APIML Gateway service port 7554 . With default settings,
if you choose LoadBalancer gateway-service , this value is optional, or set to 7554 ,
if you choose NodePort gateway-service and access the service directly, this value
should be same as spec.ports[0].nodePort with default value 32554 ,
if you choose NodePort gateway-service and access the service through port
forwarding, the value should be the forwarded port you set.
components.discovery.replicas should be set to same value of spec.replicas defined
in workloads/discovery-statefulset.yaml .
All components running in Kubernetes should use default ports:
components.api-catalog.port is 7552 ,

components.discovery.port is 7553 ,
 components.gateway.port is 7554 ,
components.caching-service.port is 7555 ,
components.jobs-api.port is 7600 ,

components.files-api.port is 7559 ,

components.app-server.port is 7556 .

components.caching-service.storage.mode should NOT be set to VSAM . redis is

suggested. Follow Redis configuration documentation to customize other Redis related variables.
Leave the value to empty for debugging purposes.
Must append and customize these 2 values into zowe.environments section:
ZWED_agent_host=<ZOWE_ZOS_HOST>

ZWED_agent_https_port=<ZOWE_ZSS_SERVER_PORT>

. A Secret, with values based upon a Zowe keystore's files, and similar to the example
samples/certificates-secret.yaml .

You need 2 entries under the data section:

keystore.p12 : which is base64 encoded PKCS#12 keystore,

truststore.p12 : which is base64 encoded PKCS#12 truststore.

And 3 entries under stringData section:

keystore.key : is the PEM format of certificate private key,

keystore.cer : is the PEM format of the certificate,

ca.cer : is the PEM format of the certificate authority.

PodDisruptionBudget
Zowe provides optional PodDisruptionBudget which can provide high availability during upgrade. By
default, Zowe defines minAvailable to be 1 for all deployments. This configuration is optional but
recommended. To apply PodDisruptionBudget , run this command:
To verify this step, run:
This should show you a list of PodDisruptionBudget like this:
HorizontalPodAutoscaler
Zowe provides optional HorizontalPodAutoscaler which can automatically scale Zowe components
based on resource usage. By default, each workload has a minimum of 1 replica and a maximum of 3 to 5
replicas based on CPU usage. This configuration is optional but recommended.
HorizontalPodAutoscaler relies on Kubernetes Metrics server monitoring to provide metrics through
the Metrics API. To learn how to deploy the metrics-server, see the metrics-server documentation. Please
adjust the HorizontalPodAutoscaler definitions based on your cluster resources, then run this
command to apply them to your cluster:
To verify this step, run:
This should show you a list of HorizontalPodAutoscaler like this:

Kubernetes v1.21+
If you have Kubernetes v1.21+, several optional changes are recommended based on Deprecated API
Migration Guide.
Kind CronJob : change apiVersion: batch/v1beta1 to apiVersion: batch/v1 on
workloads/zowe-yaml/cleanup-static-definitions-cronjob.yaml and
workloads/instance-env/cleanup-static-definitions-cronjob.yaml . apiVersion:
batch/v1beta1 will stop working on Kubernetes v1.25.

Kind PodDisruptionBudget : change apiVersion: policy/v1beta1 to apiVersion:

policy/v1 on all files in samples/pod-disruption-budget/ . apiVersion:
policy/v1beta1 will stop working on Kubernetes v1.25.
Starting, stopping, and monitoring
Version: v2.0.x LTS

After Zowe's containers are installed and configured, you can refer to the following topics that help you
manage your installation.

Starting Zowe containers

The Kubernetes cluster will automatically start as many containers as needed per service according to the
Deployment configuration.
To apply the deployment files, run this command:
Port forwarding (for minikube only)
Kubectl port-forward allows you to access and interact with internal Kubernetes cluster processes from your
localhost. For debugging or development, you might want to port forward to make Zowe gateway or
discovery service available externally quickly.
Before issuing port forward commands, make sure that gateway and discovery services pods are running.
You can run kubectl get pods -n zowe and check if the STATUS of both discovery-* and
gateway-* is RUNNING . If not, you may have to wait.

Once both STATUS shows RUNNING , run the following command to port forward:
The & sign at the command will run the command as a background process. Otherwise, the port forward
process will occupy the terminal indefinitely until canceled as a foreground service.

Verifying Zowe containers

The containers will start soon after applying the deployments.
To verify:
. kubectl get deployments --namespace zowe
 This command must show you a list of deployments including explorer-jes , gateway-service ,
app-server , etc. Each deployment should show 1/1 in READY column. It could take a moment
before all deployments say 1/1 .
. kubectl get statefulsets --namespace zowe
This command must show you a StatefulSet discovery which READY column should be 1/1 .
. kubectl get cronjobs --namespace zowe
This command must show you a CronJob cleanup-static-definitions which SUSPEND should
be False .

Monitoring Zowe containers

You can monitor Zowe containers using a UI or CLI.
Monitoring Zowe containers via UI
Kubernetes provides a container that allows you to manage your cluster through a web browser. When using
Docker Desktop, it is already installed in the namespace kubernetes-dashboard . See the Kubernetes
website for install instructions.
Metrics Server is also recommended and is required if you want to define Horizontal Pod Autoscaler. Check
if you have metrics-server Service in kube-system namespace with this command kubectl
get services --namespace kube-system . If you don't have it, you can follow this Installation
instruction to install it.
Monitoring Zowe containers via CLI
kubectl allows you to see the status of any kind of object with the get command. This applies to the
table in the configuring section but also for the pods that run the Zowe containers.
Here are a few commands you can use to monitor your environment:
kubectl get pods -n zowe lists the status of the components of Zowe.

kubectl describe pods -n zowe <podid> can see more details about each pod.
 kubectl logs -n zowe <podid> will show you the terminal output of a particular pod, with -f
allowing you to keep the logs open as new messages are added.
kubectl get nodes -n zowe -owide will tell you more about the environment you're running.

Stopping, pausing or removing Zowe containers

To temporarily stop a component, locate the Deployment component and scale down to 0 . For example,
if you want to stop the jobs-api container, run this command:
You can later re-enable a component by scaling the component back to 1 or more.
If you want to permanently remove a component, you can delete the component Deployment . To use
jobs-api as an example, run this command:
Installation checklist
Version: v2.0.x LTS

The following checklists summarize the required steps for a base installation (first-time installation) in the
order you should perform them. The checklist includes a brief description of the steps, with links to the
comprehensive information required for the installation. The checklist also identifies the roles that are
typically required to complete the step, which enables the pre-installation planning team (systems
administrator, DevOps architect, application developer, and so on) to focus on the tasks for which they are
responsible.

Addressing the prerequisites

To plan your Zowe CLI installation, review the following checklist.

Step Description Role Time Status

Estimate
Review the Systems administrator,
Zowe CLI Learn about various Zowe application developer, .25 hrs Complete,
information CLI topics systems programmer, TBD, NA
roadmap DevOps architect
Review the Read about new features
release notes and enhancements included Systems administrator, .25 Complete,
with this release of Zowe CLI DevOps architect hours TBD, NA

Install the client-side and

Address the host-side software, and Systems administrator See Complete,
requirements ensure that there is Note-1 TBD, NA
sufficient free disk space
(Optional) Install the Zowe Runtime,
Install API which includes API Systems administrator 8 hrs Complete,
Mediation Mediation Layer] TBD, NA
Layer
 Step Description Role Time Status
Estimate

Install z/OSMF Follow

z/OSMF
the steps to install Systems administrator See
Note-2
Complete,
TBD, NA
Determine the
profile types Learn about configuration Systems administrator, .25 hrs Complete,
that you want and how to use team profiles DevOps architect TBD, NA
to use
Note-1: Allow .25 hours to install the client-side software. The amount of time to install the host-side
software depends upon your site's implementation. For example, do you require z/OSMF, REST APIs to
support the Mediation Layer, or both? See the information for the specific server-side software that you
require to determine how much time to allow for complete server-side installation and configuration.
Note-2: Allow 15 to 25 hours to install and configure z/OSMF. The length of time varies depending on the
External Security Manager (ESM) that you are running in your site.
You are now ready to install Zowe CLI!

Installing Zowe CLI

To install Zowe CLI, review the following checklist.

Step Description Role Time Status

Estimate
Install Install Zowe CLI from an online registry or a Systems Complete,
Zowe CLI local package administrator .5 hrs TBD, NA
Install Use the Quick Start method if you possess
Zowe CLI prerequisite knowledge of command line tools Systems Complete,
(quick and writing scripts, and you want to get administrator .25 hrs TBD, NA
start) started with Zowe CLI quickly and easily.
 Step Description Role Time Status
Estimate
(Optional)
Install Install Zowe CLI plug-ins from an online Systems Complete,
Zowe CLI registry or a local package. administrator .25 hrs TBD, NA
plug-ins
You are now ready to configure Zowe CLI!

Configuring Zowe CLI

To configure Zowe CLI, review the following checklist.

Step Description Role Time Status

Estimate
Configure Learn how to store configuration Systems administrator, Complete,
environment options that are common to DevOps architect, .25 hrs TBD, NA
variables your environment. application developer
Configure Learn how to configure Zowe Systems administrator, Complete,
Zowe team profiles and user profiles. DevOps architect, .25 hrs TBD, NA
profiles application developer
Configure Learn how to configure Zowe Systems administrator, Complete,
daemon CLI to run as persistent DevOps architect, .25 hrs TBD, NA
mode background process (daemon). application developer
System requirements
Version: v2.0.x LTS

Before installing Zowe CLI, ensure that your environment meets the prerequisites that are described in this
article.

Client-side requirements
Zowe CLI is supported on Windows, Linux, and Mac operating systems. Meet the following requirements
before you install the CLI:
Node.js: Install a currently supported version of Node.js LTS. For a complete list of supported LTS
versions, see Nodejs Releases.
Note: You might need to restart the command prompt after installing Node.js. Issue the following
command to verify that Node.js is installed.
Important! If you are installing Zowe CLI with Node.js 16 on a Windows operating system, see Installing
Zowe CLI with Node.js 16 on Windows.
npm: Install a version of Node Package Manager (npm) that is compatible with your version of Node.js.
Note: npm is included with most Node.js installations. Issue the following command to determine your
currently installed version of npm.
See Node.js release matrix to verify that the versions are compatible.
Secure Credential Store: On Linux systems, you must install the packages gnome-keyring and
libsecret (or libsecret-1-0 on Debian and Ubuntu).

Note: For information about how to configure Secure Credential Store on headless Linux and z/Linux,
see Configure Secure Credential Store on headless Linux operating systems.
Plug-in client requirements: If you plan to install plug-ins, review the Software requirements for CLI
plug-ins.
Important! Ensure that you meet the client-side requirements for the IBM Db2 plug-in before you
install it.
Host-side requirements
Zowe CLI requires the following mainframe configuration:
IBM z/OSMF configured and running: You do not need to install the full Zowe solution to install and
use Zowe CLI. Minimally, an instance of IBM z/OSMF must be running on the mainframe before you can
issue Zowe CLI commands successfully. z/OSMF enables the core capabilities, such as retrieving data
sets, executing TSO commands, submitting jobs, and more. If Zowe API Mediation Layer (API ML) is
configured and running, Zowe CLI users can choose to connect to API ML rather than to every separate
service.
Plug-in services configured and running: Plug-ins communicate with various mainframe services.
The services must be configured and running on the mainframe before issuing plug-in commands. For
example, the IMS plug-in requires an instance of IBM IMS on the mainframe with IMS Connect (REST
services) running. For more information, see Software requirements for CLI plug-ins
Zowe CLI on z/OS is not supported: Zowe CLI can be installed on an IBM z/OS environment and run
under Unix System Services (USS). However, the IBM Db2 plug-in cannot run on z/OS due to native
code requirements. As such, Zowe CLI is not supported on z/OS and is currently experimental.

Free disk space

Zowe CLI requires approximately 100 MB of free disk space. The actual quantity of free disk space
consumed might vary depending on your operating system, the plug-ins that you install, and the user
profiles that are saved to disk.
Installing Zowe CLI
Version: v2.0.x LTS

Install Zowe™ CLI on your computer.

If your role is that of a systems administrator or you are familiar with command-line tools and want to get
started using Zowe CLI quickly, see Zowe CLI quick start. You can learn about new CLI features in the
Release notes.
After you install Zowe CLI and Zowe CLI plug-ins using your preferred installation method, see Using CLI to
learn about how to connect Zowe CLI to the mainframe, create Zowe CLI profiles and team profiles, integrate
Zowe CLI with API ML, enable daemon mode, and much, much more!

Installation guidelines
To install CLI on Windows, Mac, and Linux operating systems, follow the steps in Install Zowe CLI from npm
or Install Zowe CLI from a local package.
However, to install Zowe CLI on z/Linux, z/OS UNIX System Services (USS), or on an operating system
where the Secure Credential Store is not required or cannot be installed, use the following installation
guidelines:
To install Zowe CLI on a z/Linux operating system and you require the Secure Credential Store:
i. Follow the steps in Configure Secure Credential Store on headless Linux operating systems.
ii. Follow the steps in Install Zowe CLI from npm or Install Zowe CLI from a download.
To install Zowe CLI on a z/Linux operating system and you do not require the Secure Credential Store:
i. Follow the steps in Install Zowe CLI from npm or Install Zowe CLI from a download.
ii. Follow the steps in Configure Zowe CLI on operating systems where the Secure Credential Store is
not available.
To install Zowe CLI on a USS system or on an operating system where you cannot install the Secure
Credential Store:
i. Follow the steps in Install Zowe CLI from npm or Install Zowe CLI from a download.
ii. Follow the steps in Configure Zowe CLI on operating systems where the Secure Credential Store is
not available.
Installation notes
 As you are installing Zowe CLI, you might encounter error messages that relate to cpu-features and
ssh . You can safely ignore error messages of this type; the installation completes successfully. This
behavior can occur when you install CLI from npm and from a local package.

Prerequisites
Meet the software requirements for Zowe CLI.
Meet the software requirements for each plug-in.
Prerequisite notes
If you are installing Zowe CLI on a computer that is running Node.js 16 on a Windows operating system,
see Installing Zowe CLI with Node.js 16 on Windows.
If you are running NPM version 7 ( npm@7 ) or NPM version 8 ( npm@8 ) on a Windows operating
system, ensure that your computer is connected to the Internet.
Issue the following command before you install Zowe CLI:
Linux users might need to prepend sudo to npm commands. For more information, see
Troubleshooting Zowe CLI.

Install Zowe CLI from npm

Use the following procedure to install Zowe CLI from an npm registry:
. To install or update the core CLI, open a command-line window:
Zowe CLI is installed.
. (Optional) Address the Software requirements for CLI plug-ins. You can install most plug-ins without
meeting the requirements. However, the plug-ins will not function until you configure the back-end
APIs. The IBM Db2 plug-in requires additional configuration to install.
. (Optional) To install all available plug-ins to Zowe CLI, issue the following command:
Zowe CLI is installed on your computer. Issue the zowe --help command to view a list of available
commands. For information about how to connect the CLI to the mainframe, create profiles, integrate with
API ML, and more, see Using Zowe CLI.

Install Zowe CLI from a local package

Use the following procedure to install Zowe CLI from a local package:
. Meet the prerequisites for installing Zowe CLI.
. Navigate to Download Zowe and click the Zowe vNext CLI Core button.
. Read the End User License Agreement for Zowe and click I agree to download the core package.
zowe-cli-package-next-2022MMDD.zip  is downloaded to your computer (where MMDD
indicates the month and day of the build).
. (Optional) Meet the prerequisites for installing Zowe CLI plug-ins.
. (Optional) Navigate to Download Zowe and click the Zowe vNext CLI Plugins button to download the
plugins.
. (Optional) Read the End User License Agreement for Zowe plug-ins and click I agree to download the
plugins package.
zowe-cli-plugins-next-2022MMDD.zip is downloaded to your computer (where MMDD
indicates the month and day of the build).
. Unzip the contents of zowe-cli-package-next-2021MMDD.zip (and optionally zowe-cli-
plugins-2021MMDD.zip ) to a working directory.

. To install Zowe CLI Core, open a command-line window and issue the following commands to the
working directory that you used in Step 7:
Note: If an EACCESS error displays, see Resolving EACCESS permissions errors when installing
packages globally in the npm documentation.
. (Optional) To install Zowe CLI plug-ins, issue the following command to the working directory that you
used in Step 7:
Zowe CLI and the optional plug-ins are installed on your computer. Issue the zowe --help command to
view a list of available commands. For information about how to connect the CLI to the mainframe, create
profiles and team profiles, integrate with API ML, enable daemon mode, and more, see Using CLI.
Configuring Secure Credential Store on
Version: v2.0.x LTS

headless Linux operating systems

Perform the following configurations on headless and z/Linux operating systems.

Headless Linux requirements

Ensure that you installed the Secure Credential Store requirements that are described in System
Requirements.
Unlock the Gnome keyring to allow you to load and store credentials on headless Linux operating
systems. You can unlock the keyring manually or automatically.
Note: On z/Linux operating systems, complete the steps in Configuring z/Linux before you continue.
Unlocking the keyring manually
Issue the following commands to unlock the keyring manually. You must unlock the keyring in each user
session.
Note: The gnome-keyring-daemon -r --unlock --components=secrets prompts you to specify a
password. Press Ctrl+D twice after you specify the password.
Unlocking the keyring automatically
When you are using SSH or TTY to log in to Linux, you can configure the Gnome keyring to unlock
automatically when you log in.
Note: The following steps were tested on CentOS, SUSE, and Ubuntu operating systems. The steps do not
work on WSL (Windows Subsystem for Linux) because it bypasses TTY login. Results may vary on other
Linux distributions.
Follow these steps:
. Install the PAM module for Gnome keyring. The package name depends on your distribution:
gnome-keyring-pam : CentOS, Fedora, SUSE
 libpam-gnome-keyring : Debian, Ubuntu
. Apply the following edits to the files /etc/pam.d/login (for TTY login), and /etc/pam.d/sshd if
it exists (for SSH login).
Add the following statement to the end of the auth section:
Add the following statement to end of the session section:
. Add the following statements to ~/.bashrc . The statement lets you launch DBus, which the Gnome
keyring requires. Also the statement lets the keyring daemon start so that it is ready to be used by Zowe
CLI commands.
. Start the Gnome keyring daemon:
. Restart your computer.
Issue a Zowe CLI command that uses secure credentials to test that automatic unlock of the keyring
works.

Configuring z/Linux
The Secure Credential Store (SCS) does not contain the native, pre-built binaries that are required to access
the credential vault on z/Linux operating systems.
Because the credential manager is now a built-in function of Zowe CLI, developers must build the credential
mananger binaries on z/Linux systems during the Zowe CLI installation process.
The following steps describe how to install and build the credential store binaries on z/Linux (Red Hat
Enterprise Linux (RHEL) and Ubuntu) systems.
. Install the following Linux packages on the z/Linux system:
make
gcc-c++ (sometimes available as g++)
gnome-keyring
libsecret (sometimes available as libsecret-1-0)
libsecret-devel (sometimes available as libsecret-1-dev)
Python 3.6 or later
 Note: If you are installing the Linux packages on a z/Linux system, the system where you are
configuring SCS might require Internet access. When a site hosts its own package repositories, the
repositories might not contain all of the packages that are required to configure the SCS. In this
scenario, the z/Linux system requires Internet access to install the required packages.
. If you are configuring SCS on a Ubuntu z/Linux operating system, no further action is required. You can
now install Zowe CLI. For all other platforms (RHEL), continue to the next step.
. Enable the rhel-#-for-system-z-optional-rpms repository to download libsecret-devel.
Replace # with the major version of RHEL that is running on the z/Linux system.
If your license entitles you to this repository, issue the following command to enable it:
. If you are configuring SCS to run on RHEL V8.x or later, no further action is required. You can now install
Zowe CLI. For RHEL V7.x, continue to the next step.
. Install the Red Hat Developer Toolset to ensure that you are running a version of the gcc-c++ compiler
that can build the SCS native binaries.
Issue the following commands to enable the repositories that are required to install the toolset:
. Install the toolset:
. After you install the toolset on RHEL V7.x, you can install Zowe CLI.
Important: The SCS is installed every time that you install or update Zowe CLI. On RHEL V7.x, ensure
that the Red Hat Developer Toolset is enabled every time you install or update Zowe CLI. When you do
not enable the toolset, secure credential management is not available on the system. To ensure that the
toolset is enabled when you install Zowe CLI, issue the following commands instead of the standard
NPM install commands. For example:
When you run these commands, Zowe CLI is installed globally and the system will use the latest version
of the C++ compiler to build the native components. Refer back to the instructions to set up the Secure
Credential Storage component of the Zowe CLI.
Configure Zowe CLI on operating systems
Version: v2.0.x LTS

where the Secure Credential Store is not

available
By default, Zowe CLI attempts to store sensitive information and credentials in the operating systemʼs
credential manager. When the information cannot be stored securely, Zowe CLI displays an error when you
attempt to create V1 style profiles or a V2 configuration. The actions that are required to disable secure
credential management differ depending on the type of configuration being used.

V1 profiles
Existing V1 profiles will continue to function properly. However, it will not be possible to create new profiles
without disabling secure credential management. To disable secure credential management for V1 profiles:
. Navigate to the .zowe/settings directory.
. Modify the imperative.json file by replacing the Credential Manager override value to the
following:
. Save the changes.

Team configuration
Team configuration is stored in zowe.config.json .
Team configuration can be created without access to the Secure Credential Store. However, team
configuration does not store sensitive user information on the system. Subsequent commands prompt for
the userʼs sensitive information when it not provided on the command line, and will attempt to save it with
the new Auto Store functionality. Users may experience errors when Auto Store cannot save sensitive
information securely. To mitigate this error, disable the Auto Store functionality by changing the value of the
autoStore property from true to false in the zowe.config.json or zowe.config.user.json
file.
Example:
Installing Zowe CLI with Node.js 16 on
Version: v2.0.x LTS

Windows
There are several preferred installation workarounds when you encounter the following scenarios:
Using Node.js version 16 with npm version 8 on Windows, want to install from the TGZ, and have
restricted Internet access
Unable to install Zowe CLI while offline using the TGZ bundle
The workaround installation options are, in order of preference:
Configure NPM proxy to access the public NPM registry (npmjs.org) so that the install from TGZ can
succeed. To configure an NPM proxy:
If your proxy is HTTP: npm config set proxy <proxyUrl>
If your proxy is HTTPS: npm config set https-proxy <proxyUrl>
Install CLI from an online registry instead of TGZ. This may also require configuring an NPM proxy. See
Installing Zowe CLI from an online registry.
Downgrade NPM to version 6. To downgrade from a newer version of NPM, issue the command: npm
install -g npm@6.x

Additional Considerations
There are issues with Node 16 and bundled optional dependencies in offline node installs. Because of the
issues, the optional cpu-features package was removed from the offline .tgz file that is available from
zowe.org and Broadcom. The installation process attempts to reach a configured registry and to use any
NPM proxy configured on the system. If the attempt fails, the installation process completes normally.
cpu-features changes the SSH cipher order that is used on the zowe uss issue ssh commands,
favoring chacha20-poly1305 cipher in cases where CPUs do not have built in AES instructions. This
should not affect performance.
Install CLI from Online Registry Via Proxy
Version: v2.0.x LTS

This topic describes how to install Zowe CLI using the NPM install command when you are working behind a
proxy server. Use this installation method when your site blocks access to public npm.
You can install Zowe CLI from an online registry via proxy on Windows, macOS, or Linux operating systems:
This method requires access to an internal server that will allow you to connect to the appropriate
registries. For other installation methods, see Installing CLI.
Your default registry must be public npm (or a mirror of public npm).
If you previously installed the CLI and want to update to a current version, see Updating Zowe CLI
Follow these steps:
. Identify the proxy server, including the IP address or hostname and the port number.
If your proxy server does not require login credentials, issue the following commands to add the
proxy URL to the NPM config file:
[proxy_name]: The IP or hostname
[port_number]: The port number of the proxy server.
If your proxy server requires login credentials, issue the following commands to add the proxy
URL, with login credentials, to the NPM config file:
[username] and [password]: The required login credentials
[proxy_name]: The IP or hostname
[port_number]: The port number of the proxy server
. Ensure that you meet the System requirements for CLI.
. To install Zowe CLI, issue the following command. On Linux, you might need to prepend  sudo  to
your npm commands:
. (Optional) To install open-source Zowe plug-ins:
a. Ensure that your system meets the Software requirements for Zowe CLI plug-ins.
 b. Issue the following command to install all of the plug-ins:
Zowe CLI is installed.
. (Optional) Verify that a Zowe plug-in is operating correctly. 
[my-plugin]: The syntax for the plug-in. For example, @zowe/cics@zowe-v2-lts .
. (Optional) Test the connection to z/OSMF. See Testing connections to z/OSMF 
. (Optional) Access the Zowe CLI Help ( zowe --help ) or the Zowe CLI Web Help for a complete
reference of Zowe CLI. After you install Zowe CLI, you can connect to the mainframe directly issuing a
command, by creating user profiles and making use of them on commands, or by using environment
variables. For more information, see Displaying help.
Updating Zowe CLI
Version: v2.0.x LTS

Zowe™ CLI is updated continuously. You can update Zowe CLI to a more recent version using online registry
method or the local package method.
You must update Zowe CLI using the method that you used to install Zowe CLI.

Updating to the Zowe CLI V2 Long-term Support (v2-lts)

version
If you are running Zowe CLI version v1.8.x to v1.27.x, you can update to @zowe-v2-lts (LTS version) to
leverage the latest Zowe CLI and plug-ins functionality.
. Update Zowe CLI. Open a command line window and issue the following command:
. Update Zowe plug-ins. Issue the following command to install all Zowe plug-ins:
Note: To install a subset of the plug-ins, remove the syntax for the plug-ins that you do not want to
update. For example:
. (Optional) Migrate your Zowe CLI profiles from your current installation to your V2 installation. Issue the
following command:
Although you can run Zowe CLI V2 successfully using CLI V1 profiles, we strongly recommend using CLI
V2 profiles.
Note: Profile data is backed up in case you want to revert the profiles to your previous Zowe CLI
installation.
. (Optional) If you no longer require the profiles for your previous Zowe CLI installation, you can delete
them. Issue the following command:
Important: We do not recommend deleting the profiles from your previous Zowe CLI installation until
you have tested your V2 installation and are satisfied with its performance.
You updated to the Zowe CLI V2-LTS version!
Ensure that you review the Release Notes, which describes Notable Changes in this version. We
recommend issuing familiar commands and running scripts to ensure that your profiles/scripts are
compatible. You might need to take corrective action to address the breaking changes.

Identify the currently installed version of Zowe CLI

Issue the following command (case-sensitive):

Identify the currently installed versions of Zowe CLI plug-

ins
Issue the following command:

Update Zowe CLI from the online registry

You can update Zowe CLI to the latest version from the online registry on Windows, Mac, and Linux
computers.
Note: The following steps assume that you previously installed the CLI as described in Installing Zowe CLI
from an online registry.
. Update Zowe CLI. Open a command line window and issue the following command:
. Update Zowe plug-ins. Issue the following command to install all Zowe plug-ins:
Note: To install a subset of the plug-ins, remove the syntax for the plug-ins that you do not want to
update. For example:
. Recreate any user profiles that you created before you updated to the latest version of Zowe CLI.

Update or revert Zowe CLI to a specific version

Optionally, you can update Zowe CLI (or revert) to a known version. The following example illustrates the
syntax to update Zowe CLI to version 7.0.0:

Update Zowe CLI from a local package

To update Zowe CLI from an offline ( .tgz ), local package, uninstall your current package then reinstall
from a new package using the Install from a Local package instructions. For more information, see
Uninstalling Zowe CLI and Installing Zowe CLI from a local package.
Important! Recreate any user profiles that you created before the update.
Uninstalling Zowe CLI
Version: v2.0.x LTS

You can uninstall Zowe™ CLI from the desktop if you no longer need to use it.
Important! The uninstall process does not delete the profiles and credentials that you created when using
the product from your computer. To delete the profiles from your computer, delete them before you uninstall
Zowe CLI.
The following steps describe how to list the profiles that you created, delete the profiles, and uninstall Zowe
CLI.
. Open a command-line window.
Note: If you do not want to delete the Zowe CLI profiles from your computer, go to Step 5.
. List all configuration files that you created. Issue the following command:
Example:
. Delete all of the configuration files that are listed. Issue the following command:
Tip: For this command, use the results of the zowe config list command.
. Uninstall Zowe CLI by issuing the following command:
Note: You might receive an ENOENT error when issuing this command if you installed Zowe CLI from a
local package (.tgz) and the package was moved from its original location. In the event that you receive
the error, open an issue in the Zowe CLI GitHub repository.
The uninstall process removes all Zowe CLI installation directories and files from your computer.
. Delete the ~/.zowe or %homepath%\.zowe directory on your computer. The directory contains the
Zowe CLI log files and other miscellaneous files that were generated when you used the product.
Tip: Deleting the directory does not harm your computer.
Visual Studio Code (VS Code) Extension for
Version: v2.0.x LTS

Zowe
chat on Slack

The Zowe Explorer extension for Visual Studio Code (VS Code) modernizes the way developers and system
administrators interact with z/OS mainframes, and lets you interact with data sets, USS files and jobs. Install
the extension directly to VSCode to enable the extension within the GUI. Working with data sets and USS
files from VSCode can be more convenient than using 3270 emulators, and complements your Zowe CLI
experience. The extension provides the following benefits:
Enables you to create, modify, rename, copy, and upload data sets directly to a z/OS mainframe.
Enables you to create, modify, rename, and upload USS files directly to a z/OS mainframe.
Provides a more streamlined way to access data sets, USS files and jobs.
Lets you create, edit, and delete Zowe CLI zosmf compatible profiles.
Lets you use the Secure Credential Store plug-in to store your credentials securely in the settings.
Note: Zowe Explorer is a subcomponent of Zowe. The extension demonstrates the potential for plug-ins
powered by Zowe.

Software Requirements
Ensure that you meet the following prerequisites before you use the extension:
Get access to z/OSMF.
Install Node.js v8.0 or later.
Install VSCode.
Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST
interface. For more information, see z/OS Requirements.
Create one Zowe CLI zosmf profile so that the extension can communicate with the mainframe.
Profile notes:
You can use your existing Zowe CLI zosmf profiles that are created with the Zowe CLI v.2.0.0 or later.
 Zowe CLI zosmf profiles that are created in Zowe Explorer can be interchangeably used in the Zowe
CLI.
Optionally, you can continue using Zowe CLI V1 profiles with Zowe Explorer. For more information, see
instert link here.

Installing
Use the following steps to install Zowe Explorer:
. Address the software requirements.
. Open VSCode, and navigate to the Extensions tab on the left-hand side of the UI.
. Type Zowe Explorer in the search field.
Zowe Explorer appears in the list of extensions in the left-hand panel.
. Click the green Install button to install the extension.
. Restart VSCode.
The extension is now installed and available for use.
Note: For information about how to install the extension from a VSIX file and run system tests on the
extension, see the Developer README.
You can also watch the following videos to learn how to get started with Zowe Explorer, and work with data
sets.
Configuration
Configure Zowe Explorer in the settings file of the extension. To access the extension settings, navigate to
Manage (the gear icon) > Settings, then select Extensions > Zowe Explorer Settings. For example, you
can modify the following settings:
Data set creation settings: You can change the default creation settings for various data set types.
Follow these steps:
. Click the Edit in settings.json button under the Data Set, USS or JOBS settings that you want to edit.
. Edit the settings as needed.
. Save the settings.

Set the Temporary Folder Location: You can change the default folder location where temporary files
are stored.
Follow these steps:
i. Click the Edit in settings.json button under the Data Set, USS or JOBS settings that you want to
edit.
ii. Modify the following definition:
where /path/to/directory is the folder location that you specify.
iii. Save the settings.

Relevant Information
In this section you can find useful links and other relevant to Zowe Explorer information that can improve
your experience with the extension.
For information about how to develop for Eclipse Theia, see Theia README.
For information about how to create a VSCode extension for Zowe Explorer, see VSCode extensions for
Zowe Explorer.
Visit the #zowe-explorer channel on Slack for questions and general guidance.
Zowe Explorer Profiles
Version: v2.0.x LTS

After you install Zowe Explorer, you need to have a Zowe Explorer profile to use all functions of the
extension.
Note: You can continue using Zowe V1 profiles with Zowe Explorer V2.

Configuring team profiles

Zowe CLI team profiles simplify profile management by letting you to edit, store, and share mainframe
configuration details in one location. You can use a text editor or an IDE to populate configuration files with
connection details for your mainframe services. By default, your team configuration file is located in the
.zowe home folder, whereas the project-level configuration file is located in the main directory of your
project. You can create profiles that you use globally, given that the names of the globally-used profiles are
different from your other profile names.
Note: A project context takes precedence over global configuration.
Creating team configuration files
Create a team configuration file.
. Navigate to the explorer tree.
. Hover over DATA SETS, USS, or JOBS.
. Click the + icon.
. Select Create a New Team Configuration File.
. Chose either a global configuration file or a project-level configuration file.
. Edit the config file to include the host information and save the file.
. Refresh Zowe Explorer by either clicking the button in the notification message shown after creation,
alt+z , or the Zowe Explorer: Refresh Zowe Explorer command palette option.

Your team configuration file appears either in your .zowe folder if you choose the global configuration file
option, or in your workspace directory if you choose the project-level configuration file option. The
notification message that shows in VS Code after config file creation will include the path of the file created.
Managing profiles
You can edit your project-level or global configuration files.
Follow these steps:
. Right-click on your profile.
. Select the Add, Update, or Delete Profile options to edit the zowe config file in place.
Tip: Use the Intellisense prompts if you need assistance with filling parameters in the file.
. Save the config file.
. Refresh the view by clicking the refresh icon in the Data Sets, USS, or Jobs view.
Alternatively, press F1 to open the command palette, type and execute the Zowe Explorer: Refresh
Zowe Explorer option.
You successfully edited your configuration file.
Sample profile configuration
View the profile configuration sample. In the sample, the default lpar1.zosmf profile will be loaded upon
activation.
You can use the sample to customize your profile configuration file. Ensure that you edit the host and
port values before you work in your environment.

Working with Zowe Explorer profiles

Important! The information in this section applies to only Zowe CLI V1 profiles unless otherwise noted.
Zowe CLI V1 profiles are defined by having one yaml file for each user profile.
You must have a zosmf compatible profile before you can use Zowe Explorer. You can set up a profile to
retain your credentials, host, and port name. In addition, you can create multiple profiles and use them
simultaneously.
Follow these steps:
 . Navigate to the explorer tree.
. Click the + button next to the DATA SETS, USS or JOBS bar.
Note: If you already have a profile, select it from the drop-down menu.
. Select the Create a New Connection to z/OS option.
Note: When you create a new profile, user name and password fields are optional. However, the system
will prompt you to specify your credentials when you use the new profile for the first time.
. Follow the instructions, and enter all required information to complete the profile creation.

You successfully created a Zowe CLI zosmf profile. Now you can use all the functionalities of the
extension.
If you need to edit a profile, right-click the profile and select Update Profile option.

In addition, you can hide a profile from the explorer tree, and permanently delete a profile. When you delete
your profile permanently, the extension erases the profile from the .zowe folder. To hide or delete a profile,
right-click the profile and choose one of the respective options from the list.
Validating profiles
Note: The following information applies to Zowe CLI V1 profiles (one yaml file for each user profile) and
Zowe CLI team profiles (Zowe CLI V2).
Zowe Explorer includes the profile validation feature that helps to ensure that z/OSMF is accessible and
ready for use. If a profile is valid, the profile is active and can be used. By default, the feature is automatically
enabled. You can disable the feature by right-clicking on your profile and selecting the Disable Validation
for Profile option. Alternatively, you can enable or disable the feature for all profiles in the VS Code settings.
Follow these steps:
. Navigate to the VS Code settings.
. Open Zowe Explorer Settings.
. Enable or disable the automatic validation of profiles option.
. Restart VS Code.
Using base profiles and tokens with existing profiles
As a Zowe user, you can leverage the base profile functionality to access multiple services through Single
Sign-on. Base profiles enable you to authenticate using Zowe API Mediation Layer (API ML). You can use
base profiles with more than one service profile. For more information, see Base Profiles.
Before you log in and connect your service profile, ensure that you have Zowe CLI v6.16 or higher installed.
Accessing services through API ML using SSO
Connect your service profile with a base profile and token.
Follow these steps:
. Open Zowe CLI and issue the following command:
. Follow the onscreen instructions to complete the login process.
A local base profile is created that contains your token. For more information about the process, see
Token Management.
. Run Zowe Explorer and click the + icon.
. Select the profile you use with your base profile with the token.
The profile appears in the tree and you can now use this profile to access z/OSMF via the API Mediation
Layer.
For more information, see Integrating with API Mediation Layer.
Logging in to the Authentication Service
If the token for your base profile is no longer valid, you can log in again to get a new token with the Log in to
Authentication Service feature.
Notes:
The feature is only available for base profiles.
The feature supports only API Mediation Layer at the moment. Other extenders may use a different
authentication service.
Follow these steps:
. Open Zowe Explorer.
. Right-click your profile.
. Select the Log in to Authentication Service option.
You will be prompted to enter your username and password beforehand.
The token is stored in the corresponding base profile.
If you do not want to store your token, request from the server to end the session of your token. Use the Log
out from Authentication Service feature to invalidate the token.
Follow these steps:
. Open Zowe Explorer.
. Right-click your profile.
. Select the Log out from Authentication Service option.
Your token has been successfully invalidated.
Configuring Zowe Application Framework
Version: v2.0.x LTS

The Zowe Application ("App") Framework is configured in the Zowe configuration file. Configuration can be
used to change things such as verbosity of logs, the way in which the App server communicates with the
Mediation Layer, how ZSS operates, whether to use HTTPS or AT-TLS, what language the logs should be
set, and many more attributes.
When you install Zowe™, the App Framework is configured as a Mediation Layer client by default. This is
simpler to administer because the App framework servers are accessible externally through a single port:
API ML Gateway port. It is more secure because you can implement stricter browser security policies for
accessing cross-origin content.
You can modify the Zowe App Server and Zowe System Services (ZSS) configuration, as needed, or
configure connections for the Terminal app plugins.

Accessing the App Server

When the server is enabled and given a port within the configuration file, the App server will print a message
ZWED0031I in the log output. At that time, it is ready to accept network communication. When using the API
Mediation Layer (recommended), app-server URLs should be reached from the Gateway, and you should
additionally wait for the message ZWEAM000I for the Gateway to be ready.
When Zowe is ready, the app-server can be found at https://<zowe.externalDomain>:
<components.gateway.port>/zlux/ui/v1

(Not recommended): If the API Mediation Layer is not used, or you need to contact the App server directly,
the ZWED0031I message states which port it is accessible from, though generally it will be the same value
as specified within components.app-server.port . In that case, the server would be available at
https://<zowe.externalDomain>:<components.app-server.port>/

Accessing the Desktop

The app-server should be accessed through the gateway when both are present. When both are
ready, the Desktop can be accessed from the API Mediation Layer Gateway, such as
https://<zowe.externalDomain>:<components.gateway.port>/zlux/ui/v1/ , which will
redirect to https://<zowe.externalDomain>:
<components.gateway.port>/zlux/ui/v1/ZLUX/plugins/org.zowe.zlux.bootstrap/web/inde
x.html

Although you access the App server via the Gateway port, the App server still needs a port assigned to it
which is the value of the components.app-server.port variable in the Zowe configuration file.
(Not recommended): If the mediation layer is not used, the Desktop will be accessible from the App server
directly at /ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html

Accessing ZSS
The zss server should be accessed through the gateway when both are present. When both are ready,
ZSS can be accessed from the API Mediation Layer Gateway, such as
https://<zowe.externalDomain>:<components.gateway.port>/zss/api/v1/

Although you access the ZSS server via the Gateway port, the ZSS server still needs a port assigned to it
which is the value of the components.zss.port variable in the Zowe configuration file.
If the mediation layer is not used, ZSS directly at https://<zowe.externalDomain>:
<components.zss.port>/

Configuration file
app-server configuration
The app-server uses the Zowe server configuration file for customizing server behavior. For a full list of
parameters, requirements, and descriptions, see the json-schema document for the app-server which
describes attributes that can be specified within the configuration file section components.app-server
zss configuration
ZSS shares some parameters in common with the app-server, so you can consult the above json-schema
document to find out which parameters are valid within components.zss of the Zowe configuration file.
However, some parameters within the app-server schema are not used by ZSS, such as the node section.
A ZSS-centric schema will be available soon.

Environment variables
In the latest version of Zowe, instance.env is no longer used. However, some environment variables that
could be specified within v1 can still be set within v2 in the zowe.environments section of the server
configuration file. Environment variables starting with ZWED_ map to values that can be specified within
components.app-server and components.zss so they are redundant, but you can refer to the above
json-schema document to see which values are useful or deprecated.

Configuring the framework as a Mediation Layer client

The App Server and ZSS automatically register to the API Mediation Layer when present. If this is not
desired, registration can disabled by setting the properties components.app-
server.mediationLayer.server.enabled=false for app-server and
components.zss.mediationLayer.enabled=false for ZSS.

Setting up terminal app plugins

Follow these optional steps to configure the default connection to open for the terminal app plugins.
Setting up the TN3270 mainframe terminal app plugin
The file _defaultTN3270.json within the tn3270-ng2 app folder
/config/storageDefaults/sessions/ is deployed to the configuration dataservice when the app-
server runs for the first time. This file is used to tell the terminal what host to connect to by default. If you'd
like to customize this default, you can edit the file directly within the configuration dataservice
<components.app-
server.instanceDir>/org.zowe.terminal.tn3270/sessions/_defaultTN3270.json . Or you
can open the app, customize a session within the UI, click the save icon (floppy icon) and then copy that file
from <components.app-server.usersDir>/<your
user>/org.zowe.terminal.tn3270/sessions/_defaultTN3270.json to <components.app-
server.instanceDir>/org.zowe.terminal.tn3270/sessions/_defaultTN3270.json . Either
way, you will see a file with the following properties:
Setting up the VT Terminal app plugin
The file _defaultVT.json within the vt-ng2 app folder /config/storageDefaults/sessions/
is deployed to the configuration dataservice when the app-server runs for the first time. This file is used to
tell the terminal what host to connect to by default. If you'd like to customize this default, you can edit the file
directly within the configuration dataservice <components.app-
server.instanceDir>/org.zowe.terminal.vt/sessions/_defaultVT.json . Or you can open the
app, customize a session within the UI, click the save icon (floppy icon) and then copy that file from
<components.app-server.usersDir>/<your
user>/org.zowe.terminal.vt/sessions/_defaultVT.json to <components.app-
server.instanceDir>/org.zowe.terminal.vt/sessions/_defaultVT.json . Either way, you will
see a file with the following properties:

Network configuration
Note: The following attributes are to be defined in the Zowe configuration file.
The App Server can be accessed over HTTP and/or HTTPS, provided it has been configured for either.
HTTPS should be used, as HTTP is not secure unless AT-TLS is used. When AT-TLS is used by ZSS,
components.zss.agent.http.attls must be set to true.

HTTPS
Both app-server and zss server components use HTTPS by default, and the port parameters
components.app-server.port and components.zss.port control which port they are accessible
from. However, each have advanced configuration options to control their HTTPS behavior.
The app-server component configuration can be used to customize its HTTPS connection such as
which certificate and ciphers to use, and these parameters are to be set within components.app-
server.node.https as defined within the json-schema file

The zss component configuration can be used to customize its HTTPS connection such as which
certificate and ciphers to use, and these parameters are to be set within components.zss.agent.https
as defined within the json-schema file
HTTP
The app-server can be configured for HTTP via the components.app-server.node.http section
of the Zowe configuration file, as specified within the app-server json-schema file.
The zss server can be configured for HTTP via the components.zss.agent.http section of the Zowe
configuration file, as specified within the zss json-schema file. Note that components.zss.tls must
be set to false for HTTP to take effect, and that components.zss.agent.http.attls must be set to
true for AT-TLS to be recognized correctly.

Configuration Directories
When running, the App Server will access the server's settings and read or modify the contents of its
resource storage. All of this data is stored within a hierarchy of folders which correspond to scopes:
Product: The contents of this folder are not meant to be modified, but used as defaults for a product.
Site: The contents of this folder are intended to be shared across multiple App Server instances,
perhaps on a network drive.
Instance: This folder represents the broadest scope of data within the given App Server instance.
Group: Multiple users can be associated into one group, so that settings are shared among them.
User: When authenticated, users have their own settings and storage for the Apps that they use.
These directories dictate where the Configuration Dataservice will store content. For more information, see
the Configuration Dataservice documentation
Old defaults
Prior to Zowe release 2.0.0, the location of the configuration directories were initialized to be within the
<INSTANCE_DIR> folder unless otherwise customized. 2.0.0 does have backwards compatibility for the
existence of these directories, but <INSTANCE_DIR> folder no longer exists, so they should be migrated
to match the ones specified in the Zowe configuration file.
Folder New Location Old Location

siteDir <zowe.workspaceDirectory>/app-
server/site
<INSTANCE_DIR>/workspace/app-
server/site
 Folder New Location Old Location
insta
instanceDir <zowe.workspaceDirectory>/app- <INSTANCE_DIR>/workspace/app- isn't
server server work
is us

groupsDir <zowe.workspaceDirectory>/app-
server/groups
<INSTANCE_DIR>/workspace/app-
server/groups

usersDir <zowe.workspaceDirectory>/app-
server/users
<INSTANCE_DIR>/workspace/app-
server/users

pluginsDir <zowe.workspaceDirectory>/app-
server/plugins
<INSTANCE_DIR>/workspace/app-
server/plugins

App plugin configuration

The App framework will load plugins from Components such as extensions based upon their enabled status
in Zowe configuration. The server caches knowledge of these plugins in the
<workspaceDirectory>/app-server/plugins folder. This location can be customized with the
components.app-server.pluginsDir variable in the Zowe configuration file.

Logging configuration
For more information, see Logging Utility.
Enabling tracing
To obtain more information about how a server is working, you can enable tracing within the Zowe
configuration file via components.app-server.logLevels or components.zss.logLevels variable. For more
information on all loggers, check out the Extended documentation.
For example:
All settings are optional.
Log files
The app-server and zss will create log files containing processing messages and statistics. The log files are
generated within the log directory specified within the Zowe configuration file ( zowe.logDirectory ).
The filename patterns are:
App Server: <zowe.logDirectory>/appServer-yyyy-mm-dd-hh-mm.log
ZSS: <zowe.logDirectory>/zssServer-yyyy-mm-dd-hh-mm.log
Retaining logs
By default, the last five log files are retained. You can change this by setting environment variables within the
zowe.environments section of the Zowe server configuration file. To specify a different number of logs
to retain, set ZWED_NODE_LOGS_TO_KEEP for app-server logs, or ZWES_LOGS_TO_KEEP for zss logs. For
example, if you set ZWED_NODE_LOGS_TO_KEEP to 10, when the eleventh log is created, the first log is
deleted.
Controlling the logging location
At minimum, the log information for both app-server and zss are written to STDOUT such that messages are
visible in the terminal that starts Zowe and when on z/OS, the STC job log.
By default, both servers additionally log to files and the location of these files can be changed or logging to
them can be disabled. The following environment variables can be used to customize the app-server and
zss log locations by setting the values within the zowe.environments section of the Zowe configuration
file.
ZWED_NODE_LOG_DIR : Overrides the zowe configuration file value of zowe.logDirectory for
app-server, but keeps the default filenames.
ZWES_LOG_DIR : Overrides the zowe configuration file value of zowe.logDirectory for zss, but
keeps the default filenames.
ZWED_NODE_LOG_FILE : Specifies the full path to the file where logs will be written from app-server.
This overrides both ZWED_NODE_LOG_DIR and zowe.logDirectory . If the path is /dev/null
then no log file will be written. This option does not timestamp logs or keep multiple of them.
ZWES_LOG_FILE : Specifies the full path to the file where logs will be written from zss. This overrides
both ZWES_LOG_DIR and zowe.logDirectory . If the path is /dev/null then no log file will be
written. This option does not timestamp logs or keep multiple of them.
If the directory or file specified cannot be created, the server will run (but it might not perform logging
properly).

ZSS configuration
Running ZSS requires a Zowe configuration file configuration that is similar to the one used for the Zowe App
Server (by structure and property names). The attributes that are needed for ZSS (components.zss) at
minimum, are: port, crossMemoryServerName.
By default, ZSS is configured to use HTTPS with the same certificate information and port specification as
the other Zowe services. If you are looking to use AT-TLS instead, then you must set component.zss.tls
variable to false and define component.zss.agent.http section with port, ipAddresses, and attls: true
as shown below
(Recommended) Example of the agent body:
(Not recommended) Unsecure, HTTP example with AT-TLS:
ZSS 64 or 31 bit modes
Two versions of ZSS are included in Zowe, a 64 bit version and a 31 bit version. It is recommended to run the
64 bit version to conserve shared system memory but you must match the ZSS version with the version your
ZSS plugins support. Official Zowe distributions contain plugins that support both 64 bit and 31 bit, but
extensions may only support one or the other.
Verifying which ZSS mode is in use
You can check which version of ZSS you are running by looking at the logs. At startup, the message
ZWES1013I states which mode is being used, for example:
ZWES1013I ZSS Server has started. Version 2.0.0 64-bit

Or
ZWES1013I ZSS Server has started. Version 2.0.0 31-bit

Verifying which ZSS mode plugins support

You can check if a ZSS plugin supports 64 bit or 31 bit ZSS by reading the pluginDefinition.json file of the
plugin. In each component or extension you have, its manifest file will state if there are appFw plugin
entries. In each folder referenced by the appFw section, you will see a pluginDefinition.json file. Within that
file, if you see a section that says type: 'service' , then you can check its ZSS mode support. If the
service has the property libraryName64 , then it supports 64 bit. If it says libraryName31 , then it
supports 31 bit. Both may exist if it supports both. If it instead only contains libraryName , this is
ambigious and deprecated, and most likely that plugin only supports 31 bit ZSS. A plugin only supporting 31
bit ZSS must be recompiled for 64 bit support, so you must contact the developers to accomplish that.
Example: the sample angular app supports both 31 bit and 64 bit zss
Setting ZSS 64 bit or 31 bit mode
You can switch between ZSS 64 bit and 31 bit mode by setting the value
components.zss.agent.64bit to true or false in the Zowe configuration file. The value will not take
effect until next server restart.

Using AT-TLS in the App Framework

By default, both ZSS and the App server use HTTPS regardless of platform. However, some may wish to use
AT-TLS on z/OS as an alternative way to provide HTTPS. In order to do this, the servers must run in HTTP
mode instead, and utilize AT-TLS for HTTPS. The servers should never use HTTP without AT-TLS, it
would be insecure. If you want to use AT-TLS, you must have a basic knowledge of your security product
and you must have Policy Agent configured. For more information on AT-TLS and Policy Agent, see the z/OS
Knowledge Center.
There are a few requirements to working with AT-TLS:
You must have the authority to alter security definitions related to certificate management, and you
must be authorized to work with and update the Policy Agent.
AT-TLS needs a TLS rule and keyring. The next section will cover that information.
Note: Bracketed values below (including the brackets) are variables. Replace them with values relevant to
your organization. Always use the same value when substituting a variable that occurs multiple times.
Creating AT-TLS certificates and keyring using RACF
In the following commands and examples you will create a root CA certificate and a server certificate signed
by it. These will be placed within a keyring which is owned by the user that runs the Zowe server. Note:
These actions can be done for various Zowe servers, but in these examples we set up ZSS for AT-TLS.
You can subsitute ZSS for another server if desired.
Key variables:
Variable Value
[ca_common_name]

[ca_label]

[server_userid]

[server_common_name]

[server_label]

[ring_name]

[output_dataset_name]

Note:
[server_userid] must be the server user ID, such as the STC user.
[server_common_name] must be the z/OS hostname that runs Zowe

. Enter the following RACF command to generate a CA certificate:

. Enter the follow RACF command to generate a server certificate signed by the CA certificate:
. Enter the following RACF commands to create a key ring and connect the certificates to the key ring:
. Enter the following RACF command to refresh the DIGTRING and DIGTCERT classes to activate your
changes:
. Enter the following RACF commands to verify your changes:
 . Enter the following RACF commands to allow the ZSS server to use the certificates. Only issue the
RDEFINE commands if the profiles do not yet exist.
Note: These sample commands use the FACILTY class to manage certificate related authorizations. You can
also use the RDATALIB class, which offers granular control over the authorizations.
. Enter the following RACF command to export the CA certificate to a dataset so it can be imported by the
Zowe server:
Defining the AT-TLS rule
To define the AT-TLS rule, use the sample below to specify values in your AT-TLS Policy Agent Configuration
file:

Using multiple ZIS instances

When you install Zowe, it is ready to be used for 1 instance of each component. However, ZIS can have a
one-to-many relationship with the Zowe webservers, and so you may wish to have more than one copy of
ZIS for testing or to handle different groups of ZIS plugins.
The following steps can be followed to point a Zowe instance at a particular ZIS server.
. Create a copy of the ZIS server. You could run multiple copies of the same code by having different STC
JCLs pointing to the same LOADLIB, or run different copies of ZIS by having JCLs pointing to different
LOADLIBs.
. Edit the JCL of the ZIS STC. In the NAME parameter specify a unique name for the ZIS server, for
example:
Where ZWESIS_MYSRV is the unique name of the new ZIS.
. Start the new ZIS with whatever PROCLIB name was chosen.
. Stop the Zowe instance you wish to point to the ZIS server
. Locate the zowe configuration file for the Zowe instance, and edit the parameter
components.zss.privilegedServerName to match the name of the ZIS STC name chosen, such
as ZWESIS_MYSRV
 . Restart the Zowe instance
. Verify that the new ZIS server is being used by checking for the following messages in the ZWESLSTC
server job log:
ZIS status - Ok (name='ZWESIS_MYSRV ', cmsRC=0, description='Ok',
clientVersion=2)

Controlling access to apps

You can control which apps are accessible (visible) to all Zowe desktop users, and which are accessible only
to individual users. For example, you can make an app that is under development only visible to the team
working on it.
You control access by editing JSON files that list the apps. One file lists the apps all users can see, and you
can create a file for each user. When a user logs into the desktop, Zowe determines the apps that user can
see by concatenating their list with the all users list.
You can also control access to the JSON files. The files are accessible directly on the file system, and since
they are within the configuration dataservice directories, they are also accessible via REST API. We
recommend that only Zowe administrators be allowed to access the file system locations, and you control
that by setting the directories and their contents to have file permissions on z/OS that only allow the Zowe
admin group read & write access. You control who can read and edit the JSON files through the REST API by
controlling who can access the configuration dataservice objects URLs that serve the JSON files.
Enabling RBAC
By default, RBAC is disabled and all authenticated Zowe users can access all dataservices. To enable RBAC,
follow these steps:
. To enable RBAC, set the components.zss.dataserviceAuthentication.rbac and components.app-
server.dataserviceAuthentication.rbac variables to true in the Zowe configuration file.
Controlling app access for all users
Note:
<zowe.runtimeDirectory> variable comes from the Zowe configuration file.
 . Enable RBAC.
. Navigate to the following location:
. Copy the allowedPlugins.json file and paste it in the following location:
. Open the copied allowedPlugins.json file and perform either of the following steps:
To make an app unavailable, delete it from the list of objects.
To make an app available, copy an existing plugin object and specify the app's values in the new
object. Identifier and version attributes are required.
. Restart the app server.
Controlling app access for individual users
. Enable RBAC.
. In the user's ID directory path, in the \pluginStorage directory, create
\org.zowe.zlux.bootstrap\plugins directories. For example:

. In the /plugins directory, create an allowedPlugins.json file. You can use the default
allowedPlugins.json file as a template by copying it from the following location:

. Open the allowedPlugins.json file and specify apps that user can access. For example:
Notes:
Identifier and version attributes are required.
When a user logs in to the desktop, Zowe determines which apps they can see by concatenating
the list of apps available to all users with the apps available to the individual user.
. Restart the app server.

Controlling access to dataservices

To apply role-based access control (RBAC) to dataservice endpoints, you must enable RBAC for Zowe, and
then use a z/OS security product such as RACF to map roles and authorities to the endpoints. After you
apply RBAC, Zowe checks authorities before allowing access to the endpoints.
You can apply access control to Zowe endpoints and to your app endpoints. Zowe provides endpoints for a
set of configuration dataservices and a set of core dataservices. Apps can use configuration endpoints to
store and their own configuration and other data. Administrators can use core endpoints to get status
information from the App Framework and ZSS servers. Any dataservice added as part of an app plugin is a
service dataservice.
Defining the RACF ZOWE class
If you use RACF security, take the following steps define the ZOWE class to the CDT class:
. Make sure that the CDT class is active and RACLISTed.
. In TSO, issue the following command:
If you receive the following message, ignore it:
. In TSO, issue the following command to refresh the CDT class:
. In TSO, issue the following command to activate the ZOWE class:
For more information on RACF security administration, see the IBM Knowledge Center at
https://www.ibm.com/support/knowledgecenter/.
Creating authorization profiles
For users to access endpoints after you enable RBAC, in the ZOWE class you must create System
Authorization Facility (SAF) profiles for each endpoint and give users READ access to those profiles.
Endpoints are identified by URIs in the following format:
/ZLUX/plugins/<plugin_id>/services/<service>/<version>/<path>

For example:
/ZLUX/plugins/org.zowe.foo/services/baz/_current/users/fred

Where the path is /users/fred .

SAF profiles have the following format:
ZLUX.<zowe.rbacProfileIdentifier>.<servicename>.<pluginid_with_underscores>.
<service>.<HTTP_method>.<url_with_forward_slashes_replaced_by_periods>

For example, to issue a POST request to the dataservice endpoint documented above, users must have
READ access to the following profile:
ZLUX.1.SVC.ORG_ZOWE_FOO.BAZ.POST.USERS.FRED

For configuration dataservice endpoint profiles use the service code CFG . For core dataservice endpoints
use COR . For all other dataservice endpoints use SVC .
Creating generic authorization profiles
Some endpoints can generate an unlimited number of URIs. For example, an endpoint that performs a
DELETE action on any file would generate a different URI for each file, and users can create an unlimited
number of files. To apply RBAC to this type of endpoint you must create a generic profile, for example:
ZLUX.1.COR.ORG_ZOWE_FOO.BAZ.DELETE.**

You can create generic profile names using wildcards, such as asterisks (*). For information on generic
profile naming, see IBM documentation.
Configuring basic authorization
The following are recommended for basic authorization:
To give administrators access to everything in Zowe, create the following profile and give them UPDATE
access to it: ZLUX.**
To give non-administrators basic access to the site and product, create the following profile and give
them READ access to it: ZLUX.*.ORG_ZOWE_*
To prevent non-administrators from configuring endpoints at the product and instance levels, create the
following profile and do not give them access to it: ZLUX.1.CFG.**
To give non-administrators all access to user, create the following profile and give them UPDATE access
to it: ZLUX.1.CFG.*.*.USER.**
Endpoint URL length limitations
SAF profiles cannot contain more than 246 characters. If the path section of an endpoint URL is long enough
that the profile name exceeds the limit, the path is trimmed to only include elements that do not exceed the
limit. To avoid this issue, we recommend that appliction developers maintain relatively short endpoint URL
paths.
For information on endpoint URLs, see Dataservice endpoint URL lengths and RBAC

Multi-factor authentication configuration

Multi-factor authentication is an optional feature for Zowe.
As of Zowe version 1.8.0, the Zowe App Framework, Desktop, and all apps present in the SMP/E or
convenience builds support out-of-band MFA by entering an MFA assigned token or passcode into
password field of the Desktop login screen, or by accessing the app-server /auth REST API endpoint.
For a list of compatible MFA products, see Known compatible MFA products.
Session duration and expiration
After successful authentication, a Zowe Desktop session is created by authentication plugins.
The duration of the session is determined by the plugin used. Some plugins are capable of renewing the
session prior to expiration, while others may have a fixed session length.
Zowe is bundled with a few of these plugins:
sso-auth: Uses either ZSS or the API Mediation Layer for authentication, and ZSS for RBAC
authorization. This plugin also supports resetting or changing your password via a ZSS API. Whether
ZSS or API Mediation Layer or both are used for authentication depends upon SSO settings. Starting
with Zowe 1.28.0, SSO is enabled by default such that only API Mediation Layer is called at
authentication time. By default, the Mediation Layer calls z/OSMF to answer the authentication request.
The session created mirrors the z/OSMF session.
trivial-auth: This plugin is used for development and testing, as it always returns true for any function.
It could be used if there were specific services you did not need authentication for, while you wanted
authentication elsewhere.
When a session expires, the credentials used for the initial login are likely to be invalid for re-use, since MFA
credentials are often one-time-use or time-based.
In the Desktop, Apps that you opened prior to expiration will remain open so that your work can resume after
entering new credentials.
Configuration
When you use the default Zowe SMP/E or convenience build configuration, you do not need to change Zowe
to get started with MFA.
To configure Zowe for MFA with a configuration other than the default, take the following steps:
. Choose an App Server security plugin that is compatible with MFA. The sso-auth plugin is compatible.
. Locate the App Server's configuration file in zowe.yaml .
. Edit the configuration file to modify the section components.app-
server.dataserviceAuthentication .

. Set defaultAuthentication to the same category as the plugin of choice, as seen in its
pluginDefinition.json file. For example:
sso-auth: "saf"
trivial-auth: "fallback"
The following is an example configuration for sso-auth , as seen in a default installation of Zowe:

Administering the servers and plugins using an API

The App Server has a REST API to retrieve and edit both the App Server and ZSS server configuration
values, and list, add, update, and delete plugins. Most of the features require RBAC to be enabled and for
your user to have RBAC access to utilize these endpoints. For more information see documentation on how
to use RBAC
The API returns the following information in a JSON response:
API Description

/server (GET) Returns a list of accessible server endpoints for

the Zowe App Server.
 API Description

/server/config (GET) Returns the Zowe App Server configuration

which follows this specification.

/server/log (GET) Returns the contents of the Zowe App Server

log file.
/server/loglevels (GET) Returns the verbosity levels set in the Zowe App
Server logger.
Returns Zowe App Server environment
/server/environment (GET) information, such as the operating system
version, node server version, and process ID.

/server/reload (GET) Reloads the Zowe App Server. Only available in

cluster mode.

/server/agent (GET) Returns a list of accessible server endpoints for

the ZSS server.

/server/agent/config (GET) Returns the ZSS server configuration which

follows this specification.
/server/agent/log (GET) Returns the contents of the ZSS log file.
/server/agent/loglevels (GET) Returns the verbosity levels of the ZSS logger.
/server/agent/environment (GET) Returns ZSS environment information.
/server/logLevels/name/:componentName/level/:level Specify the logger that you are using and a
(POST) verbosity level.
/plugins (GET) Returns a list of all plugins and their
dataservices.
 API Description

/plugins (PUT) Adds a new plugin or upgrades an existing

plugin. Only available in cluster mode (default).
/plugins/:id (DELETE) Deletes a plugin. Only available in cluster mode
(default).
Swagger API documentation is provided in the <zowe.runtimeDirectory>/components/app-
server/share/zlux-app-server/doc/swagger/server-plugins-api.yaml file. To see it in HTML
format, you can paste the contents into the Swagger editor at https://editor.swagger.io/.
Note: The "agent" end points interact with the agent specified in the zowe configuration file. By default this
is ZSS.
Configuring Zowe CLI environment variables
Version: v2.0.x LTS

This section explains how to configure Zowe CLI using environment variables.
By default, Zowe CLI configuration is stored on your computer in the C:\Users\user01\.zowe directory.
The directory includes log files, profile information, and installed CLI plug-ins. When troubleshooting, refer to
the logs in the imperative and zowe folders.

Setting the CLI home directory

You can set the location on your computer where Zowe CLI creates the .zowe directory, which contains log
files, profiles, and plug-ins for the product:
Environment Description Values Default
Variable
Zowe CLI home Any valid path on your Your computer default
ZOWE_CLI_HOME
directory location computer home directory

Setting CLI log levels

You can set the log level to adjust the level of detail that is written to log files:
Important! Setting the log level to TRACE or ALL might result in "sensitive" data being logged. For example,
command line arguments will be logged when TRACE is set.
Environment Variable Description Values Default

Zowe CLI logging Log4JS log levels (OFF, TRACE,

ZOWE_APP_LOG_LEVEL
level DEBUG, INFO, WARN, ERROR, WARN
FATAL)
 Environment Variable Description Values Default
Imperative CLI Log4JS log levels (OFF, TRACE,
ZOWE_IMPERATIVE_LOG_LEVEL Framework DEBUG, INFO, WARN, ERROR, WARN
logging level FATAL)

Setting CLI daemon mode properties

By default, the CLI daemon mode binary creates or reuses a file in the user's home directory each time a
Zowe CLI command runs. In some cases, this behavior might be undesirable. For example, the home
directory resides on a network drive and has poor file performance. To change the location that the daemon
uses, set the environment variables that are described in the following table:
Platform Environment Variable Description Values Defaul
Lets you override the
complete path to the
directory that will hold <your_home_dir>/.z
daemon files related to Any valid Examples:
this user. The directory path on
All ZOWE_DAEMON_DIR can contain the following your Windows:
files: computer %HOMEPATH%\.zo
daemon.lock Linux: $HOME/.zo
daemon.sock

daemon_pid.json

Lets you override the last

two segments of the Any valid
Windows name of the path on
(only) ZOWE_DAEMON_PIPE communication pipe your \\.\pipe\%USERNAME
between the daemon computer
executable (.exe) and the
daemon.
Configuring the Zowe APIs
Version: v2.0.x LTS

Review the security considerations for Zowe APIs and learn how to prevent the Denial of Service (DoS)
attacks.
The default configuration before Zowe version 1.14.0 contains Data sets and Unix files and Jobs API
microservices which might be vulnerable to DoS attacks in the form of slow https attacks. You can add
additional configuration to the start script of these components in order to prevent resource starvation via
slow https attacks.
To update the configuration of the Data sets and Unix files component, modify the start.sh script
within the runtime component directory /zowe/runtime/components/files-api/bin .
To update the configuration of the Jobs component, modify the start.sh script within the runtime
component directory /zowe/runtime/components/jobs-api/bin .
Ensure that the -Dserver.connection-timeout=8000 parameter is set. This parameter specifies how
long the component waits to receive all the required information from the client that makes a request.
See a snippet of a configured start.sh script for the Jobs component as follows:
In version 1.14.0 and later, the preceding snippet reflects the default configuration.
Advanced Gateway features configuration
Version: v2.0.x LTS

As a system programmer who wants to configure advanced Gateway features of the API Mediation Layer,
you can customize Gateway parameters by modifying either of the following files:
<Zowe runtime directory>/components/gateway/bin/start-gateway.sh

<Zowe runtime directory>/components/gateway/manifest.yaml

zowe.yaml

The parameters begin with the -D prefix, similar to all the other parameters in the file.
Note: Restart Zowe to apply changes to the parameter.
Follow the procedures in the following sections to customize Gateway parameters according to your
preferences:
Prefer IP Address for API Layer services
SAF as an Authentication provider
Enable JWT token refresh endpoint
Change password with SAF provider
Gateway retry policy
Gateway client certificate authentication
Gateway timeouts
CORS handling
Encoded slashes
Connection limits
Routed instance header
Distributed load balancer cache
Replace or remove catalog with another service
API Mediation Layer as a standalone component
SAF resource checking

SAF as an Authentication provider

By default, the API Gateway uses z/OSMF as an authentication provider. It is possible to switch to SAF as the
authentication provider instead of z/OSMF. The intended usage of SAF as an authentication provider is for
systems without z/OSMF. If SAF is used and the z/OSMF is available on the system, the created tokens are
not accepted by z/OSMF. Use the following procedure to switch to SAF.
Follow these steps:
. Open the zowe.yaml configuration file.
. Find or add the property components.gateway.apiml.security.auth.provider and set the
value to saf .
. Restart Zowe&trade.
Authentication requests now utilize SAF as the authentication provider. API ML can run without z/OSMF
present on the system.

Enable JWT token refresh endpoint

Enable the /gateway/api/v1/auth/refresh endpoint to exchange a valid JWT token for a new token
with a new expiration date. Call the endpoint with a valid JWT token and trusted client certificate. In case of
z/OSMF authentication provider, enable API Mediation Layer for passticket generation and configure z/OSMF
APPLID. Configure Passtickets
Follow these steps:
. Open the file zowe.yaml .
. Configure the following properties:
components.gateway.apiml.security.allowtokenrefresh: true
Add this property to enable the refresh endpoint.
components.gateway.apiml.security.zosmf.applid
If you use z/OSMF as an authentication provider, provide a valid APPLID . The API ML generates a
passticket for the specified APPLID and subsequently uses this passticket to authenticate to
z/OSMF. The default value in the installation of z/OSMF is IZUDFLT .
. Restart Zowe.
Change password with SAF provider
Update the user password using the SAF Authentication provider. To use this functionality, add the
parameter newPassword on the login endpoint /gateway/api/v1/auth/login . The Gateway service
returns a valid JWT with the response code 204 as a result of successful password change. The user is
then authenticated and can consume APIs through the Gateway. If it is not possible to change the password
for any reason, the response code is 401 .
This feature is also available in the API Catalog.
This feature is also available in the API Catalog.
Use a POST REST call against the URL /gateway/api/v1/auth/login :
Note: It is a common practice to set the limit for changing the password in the ESM. This value is set by the
parameter MINCHANGE for PASSWORD . The password can be changed once. Subsequently, it is
necessary to wait the specified time period before changing the password again.
Example:
MINCHANGE=120

where:
120

Specifies the number of days before the password can be reset

Change password with z/OSMF provider
Update the user password using the z/OSMF Authentication provider. To use this functionality, add the
parameter newPassword on the login endpoint /gateway/api/v1/auth/login . The Gateway service
returns a valid JWT with the response code 204 as a result of successful password change. The user is
then authenticated and can consume APIs through the Gateway. If it is not possible to change the password
for any reason, the response code is 401 .
This feature is also available in the API Catalog.
Use a POST REST call against the URL /gateway/api/v1/auth/login :
Note: In order to use the password change functionality via z/OSMF, it is necessary to install the PTF for
APAR PH34912.

Gateway retry policy

To change the Gateway retry policy, edit properties in the <Zowe install
directory>/components/gateway/bin/start.sh file:

All requests are disabled as the default configuration for retry with one exception: the server retries GET
requests that finish with status code 503 . To change this default configuration, include the following
parameters:
ribbon.retryableStatusCodes
Provides a list of status codes, for which the server should retry the request.
Example: -Dribbon.retryableStatusCodes="503, 404"
ribbon.OkToRetryOnAllOperations
Specifies whether to retry all operations for this service. The default value is false . In this case, only
GET requests are retried if they return a response code that is listed in
ribbon.retryableStatusCodes . Setting this parameter to true enables retry requests for all
methods which return a response code listed in ribbon.retryableStatusCodes .
Note: Enabling retry can impact server resources due to request body buffering.
ribbon.MaxAutoRetries
Specifies the number of times a failed request is retried on the same server. This number is multiplied
with ribbon.MaxAutoRetriesNextServer . The default value is 0 .
ribbon.MaxAutoRetriesNextServer
Specifies the number of additional servers that attempt to make the request. This number excludes the
first server. The default value is 5 .

Gateway client certificate authentication

Beginning with release 1.19 LTS, it is possible to authenticate using client certificates. The feature is
functional and tested, but automated testing on various security systems is not complete. As such, the
feature is provided as a beta release for early preview. If you would like to offer feedback using client
certificate authentication, please create an issue against the api-layer repository. Client Certificate
authentication will move out of Beta once test automation is fully implemented across different security
systems.
Use the following procedure to enable the feature to use a client certificate as the method of authentication
for the API Mediation Layer Gateway.
Follow these steps:
. Open the zowe.yaml configuration file.
. Configure the following properties:
components.gateway.apiml.security.x509.enabled
This property is the global feature toggle. Set the value to true to enable client certificate
functionality.
components.gateway.apiml.security.zosmf.applid
When z/OSMF is used as an authentication provider, provide a valid APPLID to allow for client
certificate authentication. The API ML generates a passticket for the specified APPLID and
subsequently uses this passticket to authenticate to z/OSMF. The default value in the installation of
z/OSMF is IZUDFLT .
Note: The following steps are only required if the ZSS hostname or default Zowe user name are
altered:
. Change the following property if user mapping is provided by an external API:
components.gateway.apiml.security.x509.externalMapperUrl
Note: Skip this step if user mapping is not provided by an external API.
The API Mediation Gateway uses an external API to map a certificate to the owner in SAF. This property
informs the Gateway about the location of this API. ZSS is the default API provider in Zowe. You can
provide your own API to perform the mapping. In this case, it is necessary to customize this value.
 The following URL is the default value for Zowe and ZSS:
. Add the following property if the Zowe runtime userId is altered from the default ZWESVUSR :
components.gateway.apiml.security.x509.externalMapperUser
Note: Skip this step if the Zowe runtime userId is not altered from the default ZWESVUSR .
To authenticate to the mapping API, a JWT is sent with the request. The token represents the user that
is configured with this property. The user authorization is required to use the IRR.RUSERMAP resource
within the FACILITY class. The default value is ZWESVUSR . Permissions are set up during
installation with the ZWESECUR JCL or workflow.
If you customized the ZWESECUR JCL or workflow (the customization of zowe runtime user: // SET
ZOWEUSER=ZWESVUSR * userid for Zowe started task ) and changed the default USERID,
create the components.gateway.apiml.security.x509.externalMapperUser property and
set the value by adding a new line as in the following example:
Example:
. Restart Zowe&trade .

Gateway timeouts
Use the following procedure to change the global timeout value for the API Mediation Layer instance.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property components.gateway.apiml.gateway.timeoutmillis , and set the
value to the desired value.
. Restart Zowe&trade .
If you require finer control, you can edit the <Zowe install
directory>/components/gateway/bin/start.sh , and modify the following properties:

apiml.gateway.timeoutMillis
This property defines the global value for http/ws client timeout.
Add the following properties to the file for the API Gateway:
Note: Ribbon configures the client that connects to the routed services.
ribbon.connectTimeout
Specifies the value in milliseconds which corresponds to the period in which API ML should establish a
single, non-managed connection with the service. If omitted, the default value specified in the API ML
Gateway service configuration is used.
ribbon.readTimeout
Specifies the time in milliseconds of inactivity between two packets in response from this service to API
ML. If omitted, the default value specified in the API ML Gateway service configuration is used.
ribbon.connectionManagerTimeout
The HttpClient employs a special entity to manage access to HTTP connections called by the HTTP
connection manager. The purpose of an HTTP connection manager is to serve as a factory for new
HTTP connections, to manage the life cycle of persistent connections, and to synchronize access to
persistent connections. Internally, the connections that are managed serve as proxies for real
connections. ConnectionManagerTimeout specifies a period during which managed connections
with API ML should be established. The value is in milliseconds. If omitted, the default value specified in
the API ML Gateway service configuration is used.

CORS handling
You can enable the Gateway to terminate CORS requests for itself and also for routed services. By default,
Cross-Origin Resource Sharing (CORS) handling is disabled for Gateway routes gateway/api/v1/** and
for individual services. After enabling the feature as stated in the prodecure below, API Gateway endpoints
start handling CORS requests and individual services can control whether they want the Gateway to handle
CORS for them through the Custom Metadata parameters.
When the Gateway handles CORS on behalf of the service, it sanitizes defined headers from the
communication (upstream and downstream). Access-Control-Request-Method,Access-Control-
Request-Headers,Access-Control-Allow-Origin,Access-Control-Allow-Methods,Access-
Control-Allow-Headers,Access-Control-Allow-Credentials,Origin The resulting request to
the service is not a CORS request and the service does not need to do anything extra. The list can be
overridden by specifying different comma-separated list in the property
components.gateway.apiml.service.ignoredHeadersWhenCorsEnabled in zowe.yaml
Additionally, the Gateway handles the preflight requests on behalf of the service when CORS is enabled in
Custom Metadata, replying with CORS headers:
Access-Control-Allow-Methods: GET,HEAD,POST,DELETE,PUT,OPTIONS

Access-Control-Allow-Headers: origin, x-requested-with

Access-Control-Allow-Credentials: true

Access-Control-Allow-Origin: *

Alternatively, list the origins as configured by the service, associated with the value
customMetadata.apiml.corsAllowedOrigins in Custom Metadata.
If CORS is enabled for Gateway routes but not in Custom Metadata, the Gateway does not set any of the
previously listed CORS headers. As such, the Gateway rejects any CORS requests with an origin header for
the Gateway routes.
Use the following procedure to enable CORS handling.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property components.gateway.apiml.service.corsEnabled and set the value
to true .
. Restart Zowe&trade .
Requests through the Gateway now contain a CORS header.

Encoded slashes
By default, the API Mediation Layer accepts encoded slashes in the URL path of the request. If you are
onboarding applications which expose endpoints that expect encoded slashes, it is necessary to keep the
default configuration. We recommend that you change the property to false if you do not expect the
applications to use the encoded slashes.
Use the following procedure to reject encoded slashes.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property components.gateway.apiml.service.allowEncodedSlashes and set
the value to false .
. Restart Zowe&trade .
Requests with encoded slashes are now rejected by the API Mediation Layer.

Connection limits
By default, the API Gateway accepts up to 100 concurrent connections per route, and 1000 total concurrent
connections. Any further concurrent requests are queued until the completion of an existing request. The
API Gateway is built on top of Apache HTTP components that require these two connection limits for
concurrent requests. For more information, see Apache documentation.
Use the following procedure to change the number of concurrent connections.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property components.gateway.server.maxConnectionsPerRoute and set the
value to an appropriate positive integer.
. Find or add the property components.gateway.server.maxTotalConnections and set the value
to an appropriate positive integer.

Routed instance header

The API Gateway can output a special header that contains the value of the instance ID of the API service
that the request has been routed to. This is useful for understanding which service instance is being called.
The header name is X-InstanceId , and the sample value is discoverable-
client:discoverableclient:10012 . This is identical to instanceId property in the registration of
the Discovery service.
Use the following procedure to output a special header that contains the value of the instance ID of the API
service.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property with value
components.gateway.apiml.routing.instanceIdHeader:true .
. Restart Zowe.

Distributed load balancer cache

You can choose to distribute the load balancer cache between instances of the API Gateway. To distribute
the load balancer cache, it is necessary that the caching service is running. Gateway service instances are
reuqired to have the same DN (Distinguished name) on the server certificate.
Use the following procedure to distribute the load balancer cache between instances of the API Gateway.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property with value components.gateway.apiml.loadBalancer.distribute:
true .

. Restart Zowe.

Replace or remove the Catalog with another service

By default, the API Mediation Layer contains API Catalog as a service showing available services. As the API
Mediation Layer can be successfully run without this component it is possible to replace or remove the
service from the Gateway home page and health checks. The following section describes the behavior of the
Gateway home page and health checks.
The default option displays the API Catalog.
A value can also be applied to components.gateway.apiml.catalog.serviceId .
Examples:
none
 Nothing is displayed on the Gateway home page and the Catalog is removed from
/application/health

alternative-catalog

An alternative to the API Catalog is displayed

metrics-dashboard

A possible dashboard that could appear in place of the API Catalog

Notes:
If the application contains the homePageUrl and statusPageRelativeUrl , then the full set of
information is displayed.
If the application contains the homePageUrl the link is displayed without the UP information.
If the application contains the statusPageRelativeUrl then UP or DOWN is displayed based on
the statusPage without the link.
Use the following procedure to change or replace the Catalog service.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property components.gateway.apiml.catalog.serviceId . Set the value with
the following options:
Set the value to none to remove the Catalog service.
Set the value to the ID of the service that is onboarded to the API Mediation Layer.

API Mediation Layer as a standalone component

You can start the API Mediation Layer independently of other Zowe components. By default, the Gateway,
Zowe System Services, and Virtual Desktop start when Zowe runs. To limit consumed resources when the
Virtual Desktop or Zowe System Services are not required, it is possible to specify which components start
in the context of Zowe. No change is required during the installation process to support this setup.
Once Zowe is installed, use the following procedure to limit which components start.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property components.*.enabled and set this property to false for all
components that should not be started.
. Restart Zowe&trade .
To learn more about the related section of the environment file, see Creating and configuring the Zowe
instance directory. We recommend you open this page in a new tab.

SAF Resource Checking

The API ML can check for the authorization of the user on certain endpoints. Access to a SAF resource is
checked with ESM.
Verification of the SAF resource is provided by the following three providers:
endpoint

This is the highest priority provider, such as a REST endpoint call (ZSS or similar one). This option is
disabled by default. In Zowe, ZSS has the API to check for SAF resource authorization.
native

The Native JZOS classes from Java are used to determine SAF resource access. This is the default
provider.
dummy

This is the lowest priority provider. This is the dummy implementation and is defined in a file.
Note: Verification of the SAF resource uses the first available provider based on the specified priority. The
default configuration resolves to the native provider.
You can select a specific provider by specifying the
components.gateway.apiml.security.authorization.provider key in the zowe.yaml file.
Use the parameter value to strictly define a provider. If verification is disabled, select the endpoint option.
Follow these steps:
 . Open the file zowe.yaml .
. Find or add the property components.gateway.apiml.security.authorization.provider
and set desired value.
. Restart Zowe&trade .
Examples:
Note: To configure the endpoint provider, add the following additional property:
components.gateway.apiml.security.authorization.endpoint.enabled: true

To use the endpoint provider, customize the URL corresponding to the SAF resource authorization. By
default, the ZSS API is configured and used.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property
components.gateway.apiml.security.authorization.endpoint.url and set desired value.
The default value for ZSS API is
https://${ZWE_haInstance_hostname}:${GATEWAY_PORT}/zss/api/v1/saf-auth

. Restart Zowe&trade .
Checking providers
REST endpoint call
The REST provider calls the external API to retrieve information about access rights. To enable the feature
outside of the mainframe, such as when running in Docker, you can use a REST endpoint call using the GET
method:
Method: GET
URL: {base path}/{userId}/{class}/{entity}/{level}
Response:
Note: For more information about this REST endpoint call, see ZSS implementation.
Native
The Native provider is the easiest approach to use the SAF resource checking feature on the mainframe.
Enable this provider when classes com.ibm.os390.security.PlatformAccessControl and
com.ibm.os390.security.PlatformReturned are available on the classpath. This approach uses the
following method described in the IBM documentation: method.
Note: Ensure that the version of Java on your system has the same version of classes and method
signatures.
Dummy implementation
The Dummy provider is for testing purpose outside of the mainframe.
Create the file saf.yml and locate it in the folder, where is application running or create file mock-
saf.yml in the test module (root folder). The highest priority is to read the file outside of the JAR. A file
(inner or outside) has to exist.
The following YAML presents the structure of the file:
Notes:
Classes and resources are mapped into a map, user IDs into a list.
The load method does not support formatting with dots, such as shown in the following example:
Example: {CLASS}.{RESOURCE} Ensure that each element is separated.
The field safAccess is not required to define an empty file without a definition.
Classes and resources cannot be defined without the user ID list.
When a user has multiple definitions of the same class and resource, only the most privileged access
level loads.
Discovery Service configuration parameters
Version: v2.0.x LTS

Zowe runtime configuration parameters

As an application developer who wants to run Zowe, set the following parameters during the Zowe runtime
configuration by modifying the <Zowe install
directory>/components/discovery/bin/start.sh file:

API ML configuration
Eureka configuration

API ML configuration
apiml.discovery.userid
The Discovery service in HTTP mode protects it's endpoints with basic authentication instead of client
certificate. This parameter specifies the userid. The default value is eureka .
apiml.discovery.password
This parameter specifies the password for the basic authentication used by the Discovery Service in
HTTP mode. The default value is password .
apiml.discovery.allPeersUrls
This parameter contains the list of URLs of the Discovery Service in case of multiple instances of the
service on different host. Example:
Note: Each URL within the list must be separated by a comma.
apiml.discovery.staticApiDefinitionsDirectories
The static definition directories can be specified as a parameter at startup and will be scanned by the
Discovery Service. These directories contains the definitions of static services. Example:
apiml.discovery.serviceIdPrefixReplacer
 This parameter is used to modify the service ID of a service instance, before it registers to API ML.
Using this parameter ensures compatibility of services that use a non-conformant organization prefix
with v2, based on Zowe v2 conformance. The value of the
*apiml.discovery.serviceIdPrefixReplacer parameter is represented as a tuple that
contains two strings, separated by a comma. The format of this parameter contains the following two
elements:
First, the prefix that you want to replace in the service ID
Second, the new prefix that will be replaced
Example: The value of the parameter has the following format:
oldServiceIdPrefix,newServiceIdPrefix

Set this parameter in your Zowe YAML configuration (typically zowe.yaml ) by defining
configs.apiml.discovery.serviceIdPrefixReplacer . For example, defining it globally:

Or defining it only for lpar1 high availability instance:

Eureka configuration
The Discovery Service contains a configuration for implementing the client-side service discovery and for
defining a Eureka Server for service registry. Such configuration is shown below:
eureka.client.registerWithEureka If we make this property as true then while the server starts the
inbuilt client will try to register itself with the Eureka server.
eureka.client.registerWithEureka The inbuilt client will try to fetch the Eureka registry if we configure
this property as true.
eureka.client.serviceUrl.defaultZone A fallback value that provides the Eureka service URL for any
client that does not express a preference (in other words, it is a useful default).
More information about the other Eureka parameters can be found in the Spring Cloud Netflix Eureka
documentation.
API Gateway configuration parameters
Version: v2.0.x LTS

As an application developer who wants to change the default configuration of the API Mediation Layer, set
the following parameters by modifying the <Zowe install
directory>/components/gateway/bin/start.sh file:

Runtime configuration
Environment variables
Service configuration
Zuul configuration
Hystrix configuration
AT-TLS

Runtime configuration
This section describes runtime configuration properties.
apiml.service.hostname
This property is used to set the API Gateway hostname.
apiml.service.port
This property is used to set the API Gateway port.
apiml.service.discoveryServiceUrls
This property specifies the Discovery Service URL used by the service to register to Eureka.
apiml.service.preferIpAddress
Set the value of this property to true to advertize a service IP address instead of its hostname.
Notes:
If you set this property to true on the Discovery Service, ensure that you modify the value of
discoveryLocations: to use the IP address instead of the hostname. Failure to modify the
 discoveryLocations: value prevents Eureka from detecting registered services. As a result,
the available-replicas is empty.
Enabling this property may also cause issues with SSL certificates and Subject Alternative Name
(SAN).
apiml.cache.storage.location
This property specifies the location of the EhCache used by Spring.
Note: It is necessary for the API ML process to have write access to the cache location.
apiml.security.ssl.verifySslCertificatesOfServices
This parameter makes it possible to prevent server certificate validation.
Important! Ensure that this parameter is set to true in production environments. Setting this
parameter to false in production environments significantly degrades the overall security of the
system.
apiml.security.auth.zosmfServiceId
This parameter specifies the z/OSMF service id used as authentication provider. The service id is
defined in the static definition of z/OSMF. The default value is zosmf .
apiml.zoweManifest
This parameter lets you view the Zowe version by using the /version endpoint. To view the version
requires setting up the launch parameter of the API Gateway - apiml.zoweManifest with a path to
the Zowe build manifest.json file. This file is usually located in the root folder of Zowe build. If the
encoding of manifest.json file is different from UTF-8 and IBM1047, ensure that you set up the
launch parameter of API Gateway - apiml.zoweManifestEncoding with correct encoding.
Note: It is also possible to know the version of API ML and Zowe (if API ML used as part of Zowe), using
the /gateway/api/v1/version endpoint in the API Gateway service in the following format:
apiml.security.auth.tokenProperties.expirationInSeconds
This property is relevant only when the JWT is generated by the API Mediation Layer. API ML generation
of the JWT occurs in the following cases:
 z/OSMF is only available as an older version which does not support JWT tokens
The SAF provider is used
To use a custom configuration for z/OSMF which changes the expiration of the LTPA token, it is
necessary to also set the expiration in this parameter.
Note: The default value is 8 hours which mimicks the 8 hour default expiration of the LTPA token in
z/OSMF.
Follow these steps:
i. Open the file <Zowe install directory>/components/gateway/bin/start.sh .
ii. Find the line that contains -cp ${ROOT_DIR}"/components/gateway/gateway-
service.jar":/usr/include/java_classes/IRRRacf.jar .

iii. Before this line, add a new line in the following format:
where:
{expirationTimeInSeconds}

refers to the specific time before expiration

iv. Restart Zowe&trade.
ibm.serversocket.recover
In a multiple network stack environment (CINET), when one of the stacks fails, no notification or Java™
exception occurs for a Java program that is listening on an INADDR_ANY socket. When new stacks
become available, the Java application does not become aware of these stacks until the application
rebinds the INADDR socket. By default, this parameter is enabled in the API Gateway. As a result, the
NetworkRecycledException exception is thrown to the application to allow it to either fail or
attempt to rebind. For more information, see the IBM documentation.
java.io.tmpdir
This property is a standard Java system property which is used by the disk-based storage policies. This
property determines where the JVM writes temporary files, including those written by these storage
policies. The default value is typically /tmp on Unix-like platforms.
 spring.profiles.include
This property can be used to unconditionally add active profiles. For more information, see the Spring
documentation.
server.maxTotalConnections and server.maxConnectionsPerRoute
These two properties are used to set the number of concurrent connections. Further connection
requests that put the number of connections over either of these limits are queued until an existing
connection completes. The API Gateway is built on top of Apache HTTP components that require these
two connection limits for concurrent requests. For more information, see Apache documentation.
Environment variables
You can add additional environment variables to store configuration properties for the API Mediation Layer.
Note: Use either dot separation, or the UPPER_CASE naming convention when adding an additional
environmental variable.
One use case for adding an environmental variable is to change the authentication provider. The SAF
Authentication Provider allows the API Gateway to authenticate directly with the z/OS SAF provider
that is installed on the system. The user needs a SAF account to authenticate. Use this procedure to
customize authentication provider.
Follow the steps:
. Open the file <Zowe instance directory>/instance.env .
. Add a new line with the following property:
apiml.security.auth.provider=saf .

Service configuration
For information about service configuration parameters, see Onboarding a REST API service with the Plain
Java Enabler (PJE).

Zuul configuration
As a provider for routing and filtering, the API Gateway contains a Zuul configuration as shown in the
following example.
Example:
The Zuul configuration allows the API Gateway to act as a reverse proxy server through which API requests
can be routed from clients on the northbound edge to z/OS servers on the southbound edge.
Note: For more information about Zuul configuration parameters, see the Spring Cloud Netflix
documentation.

Hystrix configuration
The API Gateway contains a Hystrix configuration as shown in the following example.
Example:
Hystrix is a latency and fault tolerance library designed to isolate points of access to remote systems,
services and third-party libraries, stop cascading failure, and enable resilience in complex distributed
systems where failure is inevitable.
Note: For more information about Hystrix configuration parameters, see the Netflix - Hystrix documentation.

AT-TLS
The communication server on z/OS provides a functionality to encrypt HTTP communication for on-platform
running jobs. This functionality is refered to as Application Transparent Transport Layer Security (AT-TLS).
Starting with Zowe version 1.24, it is possible to leverage AT-TLS within the API Mediation Layer. Each API
ML component can run with AT-TLS rules applied. Some components, such as the Discovery service, can be
made AT-TLS aware by enabling the AT-TLS profile, whereby TLS information can be utilized. Such
information could be a client certificate. To enable the AT-TLS profile and disable the TLS application in API
ML, update zowe.yaml with following values under the respective component in the components
section:
While API ML can not handle TLS on its own, the Mediation Layer needs information about the server
certificate that is defined in the AT-TLS rule. Update the zowe.yaml file for each respective APIML
component in the components sections with the path to the SAF Key ring from the AT-TLS rule and
specify the alias that is used for Inbound communication:
Note: This procedure does not configure AT-TLS on z/OS, but rather enables API ML to work with AT-TLS in
place.
Getting started
Version: v2.0.x LTS

Learn how to start exploring the Zowe components, applications and plug-ins.
Use core components:
Using Zowe Desktop
Using Zowe API Mediation Layer
Using Zowe CLI
Using Zowe Explorer
Using Zowe SDKs
Explore available plug-ins:
Zowe CLI plug-ins
Zowe Explorer extensions
Using the Zowe Desktop
Version: v2.0.x LTS

You can use the Zowe™ Application Framework to create application plugins for the Zowe Desktop. For more
information, see Extending the Zowe Application Framework.

Navigating the Zowe Desktop

From the Zowe Desktop, you can access Zowe applications.
Accessing the Zowe Desktop
From a supported browser, open the Zowe Desktop at
https://zowe.externalDomains[0]:zowe.externalPort/zlux/ui/v1/ or you can navigate to
the direct Desktop URI at
https://zowe.externalDomains[0]:zowe.externalPort/zlux/ui/v1/ZLUX/plugins/org.zow
e.zlux.bootstrap/web/index.html

Where:
zowe.externalDomains is the host on which you are running the Zowe Application Server, its the value
that was assigned in the zowe configuration file.
zowe.externalPort is the value of Gateway port that was assigned in the zowe configuration file.
Logging in and out of the Zowe Desktop
. To log in, enter your TSO credentials in the Username and Password fields.
. Press Enter. Upon authentication of your user name and password, the desktop opens.
To log out, click the User icon in the lower right corner and click Sign Out.
Changing user password
. Open the Preferences panel by clicking on the Preferences icon in the bottom right of the desktop.

2. Click the Change Password icon. 3. Fill out the Old Password and New Password fields. 4. Upon
successful password change, you will be taken to the desktop.
Updating an expired password
. Upon logging in with an expired password, a screen will be displayed prompting you to change your
password.
. Enter and confirm your new password in the corresponding fields.
. Upon successful password change, you will be taken to the desktop.
Pinning applications to the task bar
. Click the Start menu in the bottom left corner of the home screen.
. Locate the application you want to pin.
. Right-click the application icon and select Pin to taskbar.
Open application in new tab
. Click the Start menu in the bottom left corner of the home screen.
. Locate the application you want to open in new tab.
. Right-click the application icon and select Open In New Browser Tab.
While opening an application in new tab you can also do the following:
You can use url to send data to the application, for example you would specify
https://zowe.externalDomains[0]:zowe.externalPort/ZLUX/plugins/org.zowe.zl
ux.bootstrap/web/?pluginId=org.zowe.editor:data:{"type":"openFile","name":"
<path of file>"}

You can use url to open application directly on browser with and without credentials using
showLogin in url.
Personalizing the Desktop
. Click the Preferences icon to open the Preferences panel.

. Click the Personalization icon to open the menu.

. Drag an image into the wallpaper grid, or press the upload button, to upload a new Desktop wallpaper.
. To set a new theme color, select a color from the palette or hue.
. Use the lightness swatch bar to adjust the lightness of the color.
Adjusting the lightness will also change the lightness of secondary text.
. Select a size (small, medium, or large) to adjust the scale of the Desktop UI.
Changing the desktop language
Use the Languages setting in the Preferences panel to change the desktop language. After you change the
language and restart Zowe, desktop menus and text display in the specified language. Applications that
support the specified desktop language also display in that language.
. Click the Preferences icon in the lower right corner.
. Click Languages.
. In the Languages dialog, click a language, and then click Apply.
. When you are prompted, restart Zowe.

Zowe Desktop application plugins

Application plugins are applications that you can use to access the mainframe and to perform various tasks.
Developers can create application plugins using a sample application as a guide. The following application
plugins are installed by default:
Hello World Sample
The Hello World sample application plugin for developers demonstrates how to create a dataservice and
how to create an application plugin using Angular and using React.
IFrame Sample
Github Sample Repo: sample-iframe-app
Sample Angular App
Github Sample Repo: sample-angular-app
Sample React App
Github Sample Repo: sample-react-app
3270 Terminal
The 3270 Terminal plugin provides a user interface that emulates the basic functions of IBM 3270 family
terminals. On the "back end," the plugin and the Zowe Application Server connect to any standard TN3270E
server.
VT Terminal
The VT Terminal plugin provides a user interface that emulates the basic functions of DEC VT family
terminals. On the "back end," the plugin and the Zowe Application Server connect to VT compatible hosts,
such as z/OS UNIX System Services (USS), using standard network protocols.
API Catalog
The API Catalog plugin lets you view API services that have been discovered by the API Mediation Layer. For
more information about the API Mediation Layer, Discovery Service, and API Catalog, see API Mediation
Layer Overview.
Editor
With the Zowe Editor you can create, edit, and modify the properties of files such as ownership and
permissions. You can also view and edit datasets. Navigation is controlled by the File Tree. Other actions are
available using the top left menu, a toolbar above the tree, or hotkeys.
JES Explorer
Use this application to query JES jobs with filters, and view the related steps, files, and status. You can also
purge jobs from this view.
IP Explorer
With the IP Explorer you can monitor the TCP/IP stacks, view active connections and reserved ports.
MVS Explorer
Use this application to browse the MVS™ file system by using a high-level qualifier filter. With the MVS
Explorer, you can complete the following tasks:
List the members of partitioned data sets.
Create new data sets using attributes or the attributes of an existing data set ("Allocate Like").
Submit data sets that contain JCL to Job Entry Subsystem (JES).
Edit sequential data sets and partitioned data set members with basic syntax highlighting and content
assist for JCL and REXX.
Conduct basic validation of record length when editing JCL.
Delete data sets and members.
Open data sets in full screen editor mode, which gives you a fully qualified link to that file. The link is
then reusable for example in help tickets.
USS Explorer
Use this application to browse the USS files by using a path. With the USS Explorer, you can complete the
following tasks:
List files and folders.
Create new files and folders.
Edit files with basic syntax highlighting and content assist for JCL and REXX.
Delete files and folders.
Using the Editor
Version: v2.0.x LTS

With the Zowe Editor, you can create and edit the many types of files.

Specifying a highlighting language

. Click Language on the editor menu bar. A dropdown menu will be displayed.
. From the dropdown, select the desired language. Plain Text will be chosen by default if the automatic
language detection is not able to determine the language.

Open a dataset
To open a dataset, follow these steps:
. From the File menu, select Open Datasets. You can also use (ALT+K).
. In the Dataset field, specify the name of the dataset you want to open.
. Click Open

Deleting a file or folder

. In the file tree, right-click on a file or folder you want to delete.
. From the right-click menu, click Delete. A warning dialogue will appear.
. Click Delete

Opening a directory
. From the File menu, select Open Directory. You can also use (ALT+O).
. In the Directory field, specify the name of the directory you want to open. For example: /u/zs1234
. Click Open
The File Explorer on the left side of the window lists the folders and files in the specified directory. Clicking
on a folder expands the tree. Clicking on a file opens a tab that displays the file contents. Double-clicking on
a folder will make the active directory the newly specified folder.
Creating a new directory
. Right-click on a location in the directory tree where you want to create a new directory.
. From the right-click menu, click Create a directory....
. Specify a directory name in the Directory Name field.
. The Path will be set to the location that you initially right-clicked to open the dialogue. You can specify a
different location in the Path field.
. Click Create

Creating a new file

To create a new file, complete these steps:
. From the File menu, select New File. You can also use (ALT+N).
. From the File menu, select Save to save the newly created file. You can also use (Ctrl+S)
. In the File Name field, specify the file name for the newly created file.
. Choose an encoding option from the Encoding dropdown menu. The directory will be prefilled if you are
creating the new file in an existing folder.
. Click Save
. To close a file, click the X icon in its tab, double-click on the tab, or use (Alt+W).

Hotkeys
The following hotkeys can be used in the editor to navigate or perform actions with only the keyboard.
Shift TAB: Cycle through the menu bar, browsing type, search bar, file tree, and editor component.
Individual options within the menu bar and individual nodes within the file tree can be navigated
with the arrow keys and ENTER (to select).
Hot Key Command
ALT+K Open a dataset
ALT+O Open a directory
 Hot Key Command
ALT+N Create a new file
ALT+W Close tab
ALT+W+Shift Close all tabs
CTRL+S Save file
ALT+M Navigate Menu bar (use arrow keys)
ALT+P Search Bar focus
ALT+1 Primary editing component focus
ALT+T+CTRL Undo close/close all
ALT+R+Shift Refresh active tab
ALT+PgUp(or <) Switch to left tab
ALT+PgDown(or >) Switch to right tab
ALT+B Show/hide left-hand side file tree
Using API Catalog
Version: v2.0.x LTS

As an application developer, use the API Catalog to view what services are running in the API Mediation
Layer. Through the API Catalog, you can also view the associated API documentation corresponding to a
service, descriptive information about the service, and the current state of the service. The tiles in the API
Catalog can be customized by changing values in the apiml.catalog.tile section defined in the
application.yml of a service. A microservice that is onboarded to the API Mediation Layer and configured
appropriately, registers automatically with the API Catalog and a tile for that service is added to the Catalog.
Note: For more information about how to configure the API Catalog in the application.yml, see: Add API
Onboarding Configuration.

API Versioning
See API Catalog and Versioning for more information about the API versioning.

View Service Information and API Documentation in the API

Catalog
Use the API Catalog to view services, API documentation, descriptive information about the service, the
current state of the service, service endpoints, and detailed descriptions of these endpoints.
Note: Verify that your service is running. At least one started and registered instance with the Discovery
Service is needed for your service to be visible in the API Catalog.
Follow these steps:
. Use the search bar to find the service that you are looking for. Services that belong to the same product
family are displayed on the same tile.
Example: Sample Applications, Endevor, SDK Application
. Click the tile to view header information, the registered services under that family ID, and API
documentation for that service.
Notes:
 The state of the service is indicated in the service tile on the dashboard page. If no instances of the
service are currently running, the tile displays a message that no services are running.
At least one instance of a service must be started and registered with the Discovery Service for it to
be visible in the API Catalog. If the service that you are onboarding is running, and the
corresponding API documentation is displayed, this API documentation is cached and remains
visible even when the service and all service instances stop.
Descriptive information about the service and a link to the home page of the service are displayed.
Example:

. Select the version (v1, v2) to view the documentation of a specific API version.
Example:

. Expand the endpoint panel to see a detailed summary with responses and parameters of each endpoint,
the endpoint description, and the full structure of the endpoint.
Example:

Notes:
If a lock icon is visible on the right side of the endpoint panel, the endpoint requires authentication.
The structure of the endpoint is displayed relative to the base URL.
The URL path of the abbreviated endpoint relative to the base URL is displayed in the following
format:
Example:
/{yourServiceId}/api/v1/{endpointName}

The path of the full URL that includes the base URL is also displayed in the following format:
 https://hostName:basePort/{yourServiceId}/api/v1/{endpointName}

Both links target the same endpoint location.

Swagger "Try it out" functionality in the API Catalog

The API Catalog enables users to call service APIs through the Try it out functionality. There are 2 types of
endpoints:
Public endpoints
Endpoints that are accessible without entering user credentials.
Protected endpoints
Endpoints that are only accessible by entering user credentials. These endpoints are marked with a lock
icon.
Example:

Note: Before making requests to protected endpoints, authorize your session by clicking the lock icon
and complete the required information in the Authorization modal shown below:
Example:

To demonstrate Try it out, we use the example of the Swagger Petstore.

Example:

Make a request
This section outlines the process for making a request.
Follow these steps:
 . Expand the POST Pet endpoint.
. Click Try it out.
Example:

After you click Try it out, the example value in the Request Body field becomes editable.
. In the Example Value field, change the first id value to a random value. Change the second name
value to a value of your choice, such as the name of a pet.
. Click Execute.
Example:

The API Catalog Swagger UI submits the request and shows the curl that was submitted. The
Responses section shows the response.
Example:

Static APIs refresh functionality in the API Catalog

The API Catalog enables users to manually refresh static service APIs. Use the Refresh Static APIs option if
you change a static service API and want these changes to be visible in the API Catalog without restarting
the Discovery Service.
Example:

To refresh the status of a static service, click the Refresh option located in the upper right-hand side of the
API Catalog UI. Successful requests return a pop-up notification that displays the message, The refresh
of static APIs was successful! .

Example:
If the request fails, a dialog appears with an error message that describes the cause of the fail.
Example:

Note: The manual Refresh Static APIs option applies only to static service APIs. Changes to the status of
services that are onboarded to allow for dynamic discovery require a restart of the specific services where
changes are applied. It is not necessary to restart the API Catalog or the Discovery Service.

Change password via API Catalog

In case expiration of a mainframe password, the API Catalog offers the possibility to set a new password,
using either the SAF or the z/OSMF provider. For more information about the password change functionality,
see Advanced Gateway features configuration.
Using Metrics Service (Technical Preview)
Version: v2.0.x LTS

As a system administrator, use the Metrics Service to view information about the acitivty of services running
in the API Mediation Layer. Currently, only HTTP metrics are displayed for core API Mediation Layer services.
In order for the Metrics Service to run, you must set components.metrics-service.enabled in
zowe.yaml to true . Additionally, for each APIML service you want to have metrics collected for, you
must set components.<service>.apiml.metrics.enabled set to true in zowe.yaml , or
configs.apiml.metrics.enabled set to true in the service's manifest. When metrics are enabled
for the API Gateway, the Gateway homepage displays a link to the Metrics Service dashboard. The
dashboard is available at https://{gateway_host}:{gateway_port}/metrics-service/ui/v1 .`

API Mediation Layer Metrics Service Demo Video

Watch this video to see a demo of the Metrics Service.

View HTTP Metrics in the Metrics Service Dashboard

Use the Metrics Service to view HTTP metrics such as number of requests, response times, and error rates.
The below image describes the information provided in the Metrics Service dashboard.
discoverable client api v1
To view the HTTP metrics for a service, select the corresponding tab in the Metrics Service dashboard.
Metrics are displayed for each endpoint of a service, aggregated from all service instances.
Example:

Metrics are provided on a near real-time basis, so the display shows the current activity of the selected
service. At this time there is no persistence for this information.
Service instances expose their HTTP metrics at https://<service_host>:
<service_port>/application/hystrix.stream using the Server-Sent-Events protocol. The Metrics
Service collects these streams and aggregates them across service instances before displaying.
Note: At this time, the /application/hystrix.stream endpoint for a service does not require
authentication if metrics are enabled for that service. If metrics for that service are not enabled,
/application/hystrix.stream is protected by authentication.
Using Zowe CLI
Version: v2.0.x LTS

Learn about how to use Zowe CLI, including connecting to the mainframe, managing profiles, integrating
with API Mediation Layer, and more.
You can use the CLI interactively from a command window on any computer on which it is installed, or run it
in a container or automation environment.
Tip: If you want to use the CLI together with a screen reader to provide accessibility, we recommend using
the Mac™ Terminal application enabled for Accessibility through System Preferences > Accessibility. On
Windows™, adjust the Properties settings in Command Prompt. For other operating systems, or for
alternative terminals, check the specification for the terminal to ensure that it meets accessibility
requirements.
Displaying help
Version: v2.0.x LTS

Zowe CLI has a command-line help system that details the commands, actions, and options available in the
product.

Top-level help
To view top-level help, open a command-line and issue the following command:

Alternatively, issue the following command to display a full list of all available commands:
Tip: All Zowe CLI commands begin with zowe.

Group, action, and object help

Append the global --help option to learn about a specific command group, action, or object.
For example, issue the following command to learn about the create action in the zos-files group:

Launch local web help

Launch an interactive form of help in a web browser. When you issue the following command, web help is
custom-generated to include commands for all of your currently installed plug-ins:
Tip: Append --help-web to a specific command or action to launch directly into the appropriate web help
page.

Viewing web help

We provide you with several methods to view Zowe CLI web help. You can browse Zowe CLI web help online,
download the web help in a ZIP file that contains the HTML, or download the web help in a PDF file.
Browse Online
Download (ZIP)
Download (PDF)
Understanding core command groups
Version: v2.0.x LTS

Zowe CLI contains command groups that focus on specific business processes. For example, the zos-
files command group lets you interact with mainframe data sets. This article provides a brief synopsis of
the tasks that you can perform with each group. For more information, see Displaying help.
The commands available in the product are organized in a hierarchical structure. Command groups (for
example, zos-files ) contain actions (for example, create ) that let you perform actions on specific
objects (for example, a specific type of data set). For each action that you perform on an object, you can
specify options that affect the operation of the command. Zowe CLI contains the following command
groups:

auth
The auth command group lets you connect to Zowe API Mediation Layer authentication service and obtain a
token, or disconnect from the authentication service and revoke the token.
Note: For more information about auth syntax, actions, and options, open Zowe CLI and issue the
following command:

config
The config command group lets you manage JSON projects, global configuration, and convert profiles
(service profiles and base profiles) to team profiles.
Note: For more information about config syntax, actions, and options, open Zowe CLI and issue the
following command:

daemon
The daemon command groups let you perform operations that control the daemon-mode functionality of
the Zowe CLI. Daemon-mode runs the CLI command processor as a daemon to improve performance.
Note: For more information about daemon syntax, actions, and options, open Zowe CLI and issue the
following command:
Important! Using daemon mode contains various limitations and configuration requirements, depending on
the operating system where the daemon is running. For more information, see Preparing for installation in
Using daemon mode.

plugins
The plugins command group lets you install and manage third-party plug-ins for the product. Plug-ins
extend the functionality of Zowe CLI in the form of new commands. With the plugins command group, you
can perform the following tasks:
Install or uninstall third-party plug-ins.
Display a list of installed plug-ins.
Validate that a plug-in integrates with the base product properly.
Note: For more information about plugins syntax, actions, and options, open Zowe CLI and issue the
following command:

profiles
The profiles command group lets you create and manage profiles for use with other Zowe CLI command
groups. Profiles allow you to issue commands to different mainframe systems quickly, without specifying
your connection details with every command. With the profiles command group, you can perform the
following tasks:
Create, update, and delete profiles for any Zowe CLI command group that supports profiles.
Set the default profile to be used within any command group.
List profile names and details for any command group, including the default active profile.
Note: For more information about profiles syntax, actions, and options, open Zowe CLI, and issue the
following command:

provisioning
The provisioning command group lets you perform IBM z/OSMF provisioning tasks with templates and
provisioned instances from Zowe CLI.
With the provisioning command group, you can perform the following tasks:
Provision cloud instances using z/OSMF Software Services templates.
List information about the available z/OSMF Service Catalog published templates and the templates that
you used to publish cloud instances.
List summary information about the templates that you used to provision cloud instances. You can filter
the information by application (for example, DB2 and CICS) and by the external name of the provisioned
instances.
List detail information about the variables used (and their corresponding values) on named, published
cloud instances.
Note: For more information about provisioning syntax, actions, and options, open Zowe CLI and issue
the following command:

zos-console
The zos-console command group lets you issue commands to the z/OS console by establishing an extended
Multiple Console Support (MCS) console.
With the zos-console command group, you can perform the following tasks:
Important! Before you issue z/OS console commands with Zowe CLI, security administrators should ensure
that they provide access to commands that are appropriate for your organization.
Issue commands to the z/OS console.
Collect command responses and continue to collect solicited command responses on-demand.
Note: For more information about zos-console syntax, actions, and options, open Zowe CLI and issue
the following command:

zos-files
The zos-files command group lets you interact with data sets on z/OS systems.
With the zos-files command group, you can perform the following tasks:
Create partitioned data sets (PDS) with members, physical sequential data sets (PS), and other types of
data sets from templates. You can specify options to customize the data sets you create.
 Download mainframe data sets and edit them locally in your preferred Integrated Development
Environment (IDE).
Upload local files to mainframe data sets.
List available mainframe data sets.
Interact with VSAM data sets directly, or invoke Access Methods Services (IDCAMS) to work with VSAM
data sets.
Note: For more information about zos-files syntax, actions, and options, open Zowe CLI and issue the
following command:

zos-jobs
The zos-jobs command group lets you submit jobs and interact with jobs on z/OS systems.
With the zos-jobs command group, you can perform the following tasks:
Submit jobs from JCL that resides on the mainframe or a local file.
List jobs and spool files for a job.
View the status of a job or view a spool file from a job.
Note: For more information about zos-jobs syntax, actions, and options, open Zowe CLI and issue the
following command:

zos-ssh
The zos-ssh command group lets you issue Unix System Services shell commands by establishing an SSH
connection to an SSH server. The zos-ssh command group was previously named zos-uss .
With the zos-uss command group, you can perform the following task:
Important! Before you issue z/OS UNIX System Services commands with Zowe CLI, security administrators
must provide access for your user ID to login via SSH.
Issue z/OS UNIX System Services shell commands over an SSH connection and stream back the
response.
Note: For more information about zos-ssh syntax, actions, and options, open Zowe CLI and issue the
following command:

zos-workflows
The zos-workflows command group lets you create and manage z/OSMF workflows on a z/OS system.
With the zos-workflows command group, you can perform the following tasks:
Create or register a z/OSMF workflow based on the properties on a z/OS system
Start a z/OSMF workflow on a z/OS system.
Delete or remove a z/OSMF workflow from a z/OS system.
List the z/OSMF workflows for a system or sysplex.
Note: For more information about zos-workflows syntax, actions, and options, open Zowe CLI and issue
the following command:

zos-tso
The zos-tso command group lets you issue TSO commands and interact with TSO address spaces on z/OS
systems.
With the zos-tso command group, you can perform the following tasks:
Execute REXX scripts
Create a TSO address space and issue TSO commands to the address space.
Review TSO command response data in Zowe CLI.
Note: For more information about zos-tso syntax, actions, and options, open Zowe CLI and issue the
following command:

zosmf
The zosmf command group lets you work with Zowe CLI profiles and get general information about z/OSMF.
With the zosmf command group, you can perform the following tasks:
 Create and manage your Zowe CLI zosmf profiles. Profiles let you store configuration information for
use on multiple commands. You can create a profile that contains your username, password, and
connection details for a particular mainframe system, then reuse that profile to avoid typing it again on
every command. You can switch between profiles to quickly target different mainframe subsystems. For
more information, see Using profiles.
Verify that your profiles are set up correctly to communicate with z/OSMF on your system. For more
information, see Test Connection to z/OSMF.
Get information about the current z/OSMF version, host, port, and plug-ins installed on your system.
Note: For more information about zosmf syntax, actions, and options, open Zowe CLI and issue the
following command:
Issuing your first command
Version: v2.0.x LTS

You can provide all connection options directly on commands to access a service. For example, issue the
following command to list all data sets under the name ibmuser on the specified system:
If you omit username, password, host, or port (and a value cannot be found in your configuration), the CLI
prompts you to enter a value.
Using daemon mode
Version: v2.0.x LTS

Daemon mode significantly improves the performance of Zowe CLI commands by running Zowe CLI as a
persistent background process (daemon). Running Zowe CLI as daemon lets Zowe absorb the one-time
startup of Node.js modules, which results in significantly faster responses to Zowe commands.
When you run Zowe in daemon mode, you run all Zowe commands as you normally run them. The first time
you run a command, it starts the daemon in the background automatically and runs your desired Zowe
command. Since the first Zowe command starts the daemon, the first command usually runs slower than a
traditional Zowe command. However, subsequent Zowe commands run significantly faster. The daemon
continues to run in the background until you close your terminal window.
Important: We do not recommend using daemon mode in an environment where multiple users use the
same system. For example, a shared Linux server.

Preparing for installation

Review the following installation notes before you configure Zowe CLI to run in daemon mode:
Daemon mode does not function on z/OS UNIX System Services (USS) systems.
When you want to run Zowe CLI to run in daemon mode on z/Linux operating systems, you must build
the daemon mode binary on the z/Linux systems. For information about how to build the binary, see
Configure Secure Credential Store on headless Linux operating systems. The sections Enable daemon
mode and Disable daemon mode (in this article) do not apply to running Zowe CLI in daemon mode on
z/Linux operating systems.
We do not recommend using daemon mode in an environment where multiple users use the same
system. For example, a shared Linux server.
When you are running Zowe on a Windows operating system in a virtual environment (for example,
Windows Sandbox), you might receive an error message that indicates that a library named
VCRUNTIME140.dll is missing. To correct the error, install Visual C++ Redistributable for Visual
Studio 2015. For more information, see Download Visual C++ Redistributable for Visual Studio 2015.

Enable daemon mode

The following steps describe how to enable daemon mode and how to configure Zowe to run Zowe CLI
constantly in daemon mode.
. Open a terminal window and issue the following command:
The command copies the Zowe executables for your operating system into the
$ZOWE_CLI_HOME/bin ( .zowe/bin ) directory. The next command that you issue starts the
daemon.
. Add the path to the Zowe executable to your PATH environment variable. For example:
Important! Ensure that you position the path to your Zowe executables before the path into which NPM
installed the Node.js script. For example, C:\Program Files\nodejs\zowe.cmd . For information
about configuring environment variables, see the documentation for your computer's operating system.
Alternative configuration: By default, the daemon binary creates or reuses a file in the user's home
directory each time a Zowe CLI command runs. In some cases, this behavior might be undesirable. To
change the location that the daemon uses, see Setting CLI daemon mode properties.
Note: Complete the environment variable configuration step (Step 2) only once.
The following example illustrates running Zowe CLI commands with daemon mode enabled:
Note: When you are running Zowe CLI in daemon mode using a Git Bash terminal on a Windows operating
system, special characters might display using the wrong code page. For example, the default code page
437 renders a form-feed character (\f) as an emoji (♀). To correct the problem, issue the command
chcp.com 65001 to change the code page to UTF-8. If you want the change to be persistent, add the
command to your .bashrc file.

Restart daemon mode

Daemon mode is a long-running background process (waits for work) that significantly improves Zowe CLI
performance. When you make changes to your work environment, daemon mode does not capture the
changes. Restarting daemon mode lets the daemon capture the changes. Issue the following command to
stop the currently running daemon and start a new daemon:
You must restart daemon mode under the following scenarios:
You changed the value of any of the following Zowe CLI environment variables:
 ZOWE_CLI_HOME

ZOWE_APP_LOG_LEVEL

ZOWE_IMPERATIVE_LOG_LEVEL

You installed, updated, or uninstalled a plug-in.

You installed a newer version of Zowe CLI and daemon mode was running while you installed the newer
version of Zowe CLI.
Note: When you install another version of Zowe CLI, you should always run the zowe daemon
enable command again.

You issued a Zowe command and the following message appeared:

Disable daemon mode

You can disable Zowe from running in daemon mode at any time. For example, daemon mode lacks
functionality that you desire, such as viewing colored-coded commands.
. Open a terminal window and issue the following command:
The disable command stops daemon mode, removes the Zowe executables from your .zowe/bin
directory, and disables daemon mode.
Configure daemon mode on z/Linux
Version: v2.0.x LTS

operating systems
Currently, Zowe does not offer a prebuilt daemon that can run on z/Linux operating systems. However,
developers can build the daemon binary from source.
The following steps describe how to install and build the daemon binary on z/Linux systems and the
technical limitations.
. Ensure that the z/Linux system can communicate using the Internet.
. Install Zowe CLI on the z/Linux system.
. Install the following Linux packages on the z/Linux system:
make
gcc-c++ (or g++)
git
Rust
For information about how to install Rust, see the Rust documentation.
. Shallow clone the Zowe CLI Git repository for the version of CLI that you installed. Issue the following
command:
. Change to the following directory:
. Build the daemon binary. Issue the following command from the zowe-cli/zowex directory:
After the command completes successfully, the Zowe daemon binary is a file named zowe that can be
found in the target/release directory.
. Copy the binary to another location on the system and add it to your PATH.
. (Optional) Modify the file permissions to allow others to use the same binary:
Example: The following example illustrates the command to allow all users to run the Zowe binary.
However, only the user that created the binary can overwrite the binary.
Note: You can delete the .zowe-cli folder that was created in Step 4 after the binary builds
successfully. The Zowe daemon commands will not function, and the daemon will need to be rebuilt for
all new versions of Zowe CLI.
Using profiles
Version: v2.0.x LTS

As a system programmer, profiles let you store configuration details for reuse, and for logging in to
authentication servers such as API Mediation layer. Create a profile that contains your username, password,
and connection details for a mainframe service, then use that profile to avoid typing the information on every
command. Switch between profiles to quickly target different mainframe subsystems.

Zowe CLI profile types

Zowe CLI contains the following types of profiles:
Team profiles simplify profile management by letting you edit, store, and share mainframe
configuration details in one location. You can use a text editor to populate global profiles with
connection details for your mainframe services.
For more information, see Configuring team profiles.
Service profiles: let you store connection information for specific mainframe service, such as IBM
z/OSMF. Plug-ins can introduce other service profile types, such as the cics profile to connect to IBM
CICS.
Base profiles: let you store connection information for use with one or more services. Your service
profiles can pull information from- base profiles as needed, so that you can specify a common
username and password once. The base profile can optionally store tokens to connect to Zowe API
Mediation Layer, which improves security by enabling Multi-Factor Authentication (MFA) and Single
Sign-on (SSO).
Tips for using Zowe CLI profiles
You can have multiple service profiles and multiple base profiles.
Profiles are not required. You can choose to specify all connection details for every command.
Profile values are stored on your computer in plaintext in C:\Users\
<yourUsername>\.zowe\profiles (Windows) or in ~/.zowe/profiles (Mac/Linux).

Important information about team profiles

 With the introduction of team profiles, the Secure Credential Store (SCS) Plug-in is deprecated. Secure
credential encryption is now handled by the the secure array in the zowe.config.json file.
You can convert all of your Zowe CLI and Zowe CLI plug-ins V1 profiles to team profiles by issuing the
following command:
Note: You can continue using Zowe CLI and Zowe CLI plug-ins V1 profiles with Zowe CLI V2. However,
we highly recommend that you implement V2 profiles with Zowe CLI V2.
Commands in the zowe config command group now let you manage security for any option value.
The zowe scs and zowe config command groups were repurposed to work with team profiles.
Zowe CLI V2 prompts you to enter the username and password securely by default.

Displaying profile help

Use help to learn about options for creating profiles. For example, for a zosmf profile, issue the following
command:

Service profiles
Create profiles that target a specific mainframe service, then use profiles to issue commands. For example,
issue the following command (substituting your connection details) to create a zosmf service profile
named myprofile123 :
Use the profile. For example, issue the following command to list all data sets under the name ibmuser on
the system that you specified in your profile:
Note: If you do not specify a profile, your default profile is used. The first profile that your create is your
default. You can set a service profile as your default with the zowe profiles set-default
<profileType> <profileName> command.

Base profiles
Base profiles store your connection details and provide them to service profiles and commands as needed.
The base profile can also contain a token to connect to services through API ML.
For example, if you use the same username and password across multiple services, you can create a base
profile with your username and password. After the base profile is created, you can omit the --username
and --password options when you issue commands or use service profiles such as zosmf and tso .
Commands will use the values provided by the base profile. For example, create the base profile:
The first profile that you create for a service is set as your default profile. When you create subsequent
profiles, you can select one as the default with the zowe profiles set-default <profileType>
<profileName> command.

Use the default profile to issue a command:

Note: If you choose to log in to Zowe API Mediation Layer, a base profile is created for you to store a web
token, host, and port.
Tips for using base profiles
Use the base profile to share option values between services. You might share option values between
services in the following situations:
You have multiple services that share the same username, password, or other value.
You want to store a web token to access all services through Zowe API Mediation Layer.
You want to trust a known self-signed certificate or your site does not have server certificates
configured. You can define reject-unauthorized in the base profile with a value of false to apply
to all services. Understand the security implications of accepting self-signed certificates at your site
before you use this method. If you have multiple LPARs and want to share option values only between
services that run on the same LPAR, you can use nested profiles to achieve this (see Example 1 below).

Profile best practices

According to order of precedence, base profiles are used as a fallback for service profiles. This means that
after you create a base profile, you might need to update your service profiles to remove username,
password, host, and port. Otherwise, commands will use the information stored in your service profile and
will ignore your base profile definition.

Testing connections to z/OSMF

Optionally, issue a command at any time to receive diagnostic information from the server and confirm that
Zowe CLI can communicate with z/OSMF or other mainframe APIs.
Important! By default, the server certificate is verified against a list of Certificate Authorities (CAs) trusted
by Mozilla. This handshake ensures that the CLI can trust the server. You can append the flag --ru false
to the following commands to bypass the certificate verification against CAs. If you use the --ru false
flag, ensure that you understand the potential security risks of bypassing the certificate requirement at your
site. For the most secure environment, system administrators configure a server keyring with a server
certificate signed by a Certificate Authority (CA). For more information, see Working with certificates.
Without a profile
Verify that your CLI instance can communicate with z/OSMF:
Default profile
After you create a profile, verify that you can use your default profile to communicate with z/OSMF:
Specific profile
After you create a profile, verify that you can use a specific profile to communicate with z/OSMF:
The commands return a success or failure message and display information about your z/OSMF server, such
as the z/OSMF version number. Report failures to your systems administrator and use the information for
diagnostic purposes.
Using team profiles
Version: v2.0.x LTS

This version of Zowe CLI (V2) introduces the concept of team profiles.
Using team profiles helps to improve the initial setup of Zowe CLI by making service connection details
easier to share and easier to store within projects.
Consider the following benefits of using team profiles:
As an application developer or team member, you can manage your connection details efficiently in one
location.
As a Dev-Ops advocate, or team leader, you can share global profiles with your team members so that
they can easily access mainframe services. You can add the file directly to your project in a software
change management (SCM) application.
As a Dev-Ops advocate, you can quickly onboard new application developers by sharing the
configuration file that your team uses with the new team member.
As an application developer in a small shop where your role is that of an application developer and a
Dev-Ops advocate, you can create team profiles, base profiles, or service profiles; whatever profile type
is most suitable for your needs!
Important: With the introduction of team profiles, the Secure Credential Store (SCS) Plug-in is deprecated.
The zowe scs and zowe config command groups are obsolete. Secure credential encryption is now
included in the core CLI. The CLI prompts you to enter the username and password securely by default.
Commands in the zowe config command group now let you manage security for any option value.
Initializing team configuration
Version: v2.0.x LTS

You can use one of the following methods to initialize team configuration.
Tip: If API Mediation Layer is running on your site, Connecting profiles to API Mediation Layer is the
recommended method to use to initialize team configuration.

Create team profile configuration files

. Issue the following command:
Zowe CLI responds with prompts for a username and password.
. Respond to the prompts with a username and password for a mainframe service such as z/OSMF.
The zowe config init command ensures that your credentials are stored securely on your
computer by default.
After you respond, the zowe.config.json team configuration file is added to your local .zowe
directory. You can then use a text editor or IDE, such as Visual Studio Code, to add the connection
details for your mainframe services.
. (Optional) Issue a Zowe CLI command to test that you can access z/OSMF.
Example: List all data sets under your user ID:
A list of data sets is returned. You successfully configured Zowe CLI to access a z/OSMF instance.
If the CLI returns an error message, verify that you have access to the target system. Examine your
configuration files in a text editor to verify that the information you entered is correct.
Important: After the configuration files are in place (either by using the zowe config init command or
by manually creating the files), the now-deprecated zowe profiles commands no longer function. Zowe CLI
returns errors when you attempt to use deprecated profile commands.

Connecting profiles to API Mediation Layer

If you are using the API Mediation Layer, you can set up your zowe.config.json file to automatically
access the services that are registered to the API ML by issuing the following command:
After you issue the command, Zowe CLI prompts you to specify the following information:
The host name and port to your API ML instance
Your username and password
Using Certificates:
If you are using certificates to authenticate, you can specify the details for the certificates by issuing the
following command:
Team configuration for application
Version: v2.0.x LTS

developers
As an application developer or Zowe CLI user, you want to manage your connection details efficiently and in
one location.

Initializing user-specific configuration

As an application developer, you can optionally generate a user-specific configuration file that overrides the
values defined in the global zowe.config.json file.
To generate a profile configuration file ( zowe.config.json ) that you can use globally, issue the following
command:
To generate the global user profile configuration file ( zowe.config.user.json ), issue the following
command:
In your user-specific file , observe that the "defaults" object is empty and the profiles do not have properties
(illustrated in the following example). You can add your connection details as properties here to override
properties in zowe.config.json , or add add new connections.

Editing team profiles

After the initial setup, as an application developer you can define additional mainframe services to the team
(or user-specific) configuration file.
Open the ~/.zowe/zowe.config.json file in a text editor or an IDE (such as Visual Stuide Code) on
your computer. The profiles object contains connection and other frequently needed information for
accessing various services.
Example:
Team configuration for team leaders
Version: v2.0.x LTS

As a Dev-Ops advocate or team leader, you can share team profiles with your team members so that they
can easily access mainframe services.

Sharing team configuration files

As a DevOps advocate or team leader, you might want to share a team configuration globally in the following
scenarios:
You want to share profiles with application developers so that they can work with a defined set of
mainframe services. The recipient of the file places it in their local ~/.zowe folder manually before
issuing CLI commands.
You want to add the profiles to your project directory in a software change management (SCM) tool,
such as GitHub. When you store the profiles in an SCM, application developers can pull the project to
their local computer and use the defined team or global configuration. Zowe CLI commands that you
issue from within the project directory use the configuration scheme for the project automatically.
You want to enable test automation a CI/CD pipeline, which lets your pipelines make use of the project
configuration.
For information about how to share team configuration files, see Sharing team configuration files.

Profile scenarios
The following topics describe various profile scenarios that DevOps advocates (team leaders) can share with
their teams, and application developers that function as DevOps advocates can create.
Access to one or more LPARs that contain services that share the same
credentials
The following example illustrates that the settings are using nested profiles to access multiple services
directly on one or more LPARs that share the same username and password.
Access to one or more LPARs contain services that do not share the same
credentials
The following example illustrates that the settings are using nested profiles to access multiple services
directly on one or more LPARs that do not share (different) user names and passwords.
Access to LPARs that access services through one API Mediation Layer
The following example illustrates that the settings access multiple services using the API ML where multi-
factor authentication (MFA) or single sign-on (SSO) is achievable using token-based authorization.
Access to LPARs that access services through one API Mediation Layer using
certificate authentication
Access LPARs containing multiple services through API Mediation Layer with certificate authentication
Sharing team configuration files
Version: v2.0.x LTS

Team leaders can share team configuration files using several methods:
Shared network drive
Project repository (for example, GitHub)
Web server
The following topics describe how to share the team configuration files.

Network drive
. Store the configuration files on a shared network drive.
. Issue the following command:
DriveLetter:
The drive letter of the shared network drive
FolderPath:
The directory path on the drive
Note: You can specify any path that file management applications, such as Windows Explorer and
Finder, can access. For example, a UNC network path ( \\
<HostName>\SharedZoweConfig\zowe.config.json ) or local file path ( C:\Users\
<UserName>\Downloads\zowe.config.json ).

Project repository and web server

Team leaders can import configuration files from a web URL that is in raw json format. The following steps
describe how to import the configuration file from a GitHub repository and a web server.
. Store the configuration files in a project repository or on a web server.
. Issue the following command:
Project (GitHub) repository
user
Specifies the user ID
password
Specifies the password for the user ID
githuburl
Specifies the URL to the GitHub repository
repoName
Specifies the name of the repository
branch
Specifies the name of the branch that contains the configuration file
folderPath
Specifies the path to the configuration file
Web server
user
Specifies the user ID
password
Specifies the password for the user ID
hostname
Specifies the host name of the system
folderPath
Specifies the path to the team configuration file
 Note: You can host team configuration files on private and public web servers. The user
name and password are required for only private URLs. However, to maintain the highest level
of security, you should not store team configuration files on public URLs.
Tip: To import the schema automatically from shared drives and from web servers, store the schema in the
same directory as the zowe.config.json file. In the configuration file, reference the schema as a relative
path at the top of the configuration file.
Example:
Managing credential security
Version: v2.0.x LTS

When you first run the zowe config init --global-config command, the
profiles.base.properties.user and profiles.base.properties.password fields are defined
to the "secure" array in your configuration file, which helps to ensure that the username and password are
stored securely on your computer.
To store or update values for the secure fields (for example, when you want to change your username and
password), issue the zowe config secure command. If, for example, you want to update several
property values in a long list of properties, press Enter to skip a field.
To secure a specific field, issue zowe config set --secure <property-path> . For example, zowe
config set --secure profiles.base.properties.password . When you issue the command for
an option that is already secured, the CLI prompts you to enter a new option value.
You can use an editor to define options to the secure array in zowe.config.json . Any option that you
define to there becomes secure/prompted-for.

Changes to secure credential storage

With the introduction of team profiles in Zowe CLI V2, the Secure Credential Store (SCS) Plug-in is
deprecated. The zowe scs and zowe config command groups are obsolete. Secure credential
encryption is now included with the Zowe CLI core application.
Zowe CLI V2 prompts you to enter the username and password securely by default. Commands in the
zowe config command group let you manage security for any option value.
Storing properties automatically
Version: v2.0.x LTS

When you issue a command that is missing a required option value for a property (for example, host or
password) the CLI prompts you to enter the option value. In the V1-LTS version of Zowe CLI, the value that
was specified was not stored for future commands to use. As a result, you either responded to a prompt on
every command issued or issued a profile update command to store the missing value.
The autoStore property in the zowe.config.json file lets you store the option values for properties
automatically. When you specify the autoStore property in zowe.config.json to true , the value
that you enter when prompted is stored for future commands to use. The values for secure fields are stored
securely in the credential vault, and the other values are written to zowe.config.json on disk.
The default value of the autoStore property is true. However, if this behavior is undesirable (you do not
want to store properties automatically), set the value of autoStore to false. A value of false uses the V1-
LTS behavior, which prompts for missing values on all commands that you issue.
Integrating with API Mediation Layer
Version: v2.0.x LTS

Zowe API ML provides a single point of access to a defined set of mainframe services. The layer provides
API management features such as high-availability, consistent security, and a single sign-on (SSO) and
multi-factor authentication (MFA) experience.
You can access services through API ML without reauthenticating every time you issue a command. Tokens
allow for a secure interaction between the client and server. When you issue commands to API ML, the layer
routes requests to an appropriate API instance based on system load and available API instances.

How token management works

When you log in with the CLI, an API ML token is supplied and stored on your computer in place of username
and password. The token allows for a secure handshake with API ML when you issue each command, such
that you do not need to reauthenticate until the token expires.
Note: Zowe CLI also supports standard token implementations such as Java Web Tokens (JWT) and
Lightweight Third-Party Authentication (LTPA).

Logging in
To request a token and "log in" to API ML, issue the following command:
The CLI prompts you to enter your username, password (where password can be a PIN concatenated with a
second factor for MFA), host, and port for the API ML instance.
Tip: If you already created a base profile, you might not be prompted for host and port.
A local base profile is created that contains your token. When you issue commands, you can omit your
username, password, host, and port. Instead, provide a base path and base profile on commands to connect
to API ML.
Optionally, when you do not want to store the token on disk, append the --show-token option to the
login command. If you choose this option, you must manually supply the token on each command using the
--token-value option.
Notes:
Tokens expire after a period of time defined by your security administrator. When a token expires, you
must log in again to get a new token.
If you omit connection details from a service profile, such as zosmf profile, the CLI uses the
information from your base profile.
You can choose to specify all connection details on a service profile and connect directly to the service.
Routing through API ML is not required.

Logging out
Log out to expire the API ML token and remove it from your base profile.
Issue the following command:
zowe auth logout

The token is expired. Log in again to obtain a new token.

Accessing a service through API ML

To access services through API ML using the token in your base profile, specify the following options on
commands and service profiles:
--base-path : The base path of the API ML instance that you want to access.

--disable-defaults : Specify this flag to prevent default values from being stored in service
profiles. If you do not use this flag, the defaults can override values in your base profile.
Note: Ensure that you do not provide username, password, host, or port directly on the service commands
or profiles. Supplying those options causes the CLI to ignore the API ML token in your base profile and
directly access the service.
Specifying a base path
The following example illustrates a complete path for a z/OSMF instance registered to API ML. The format of
base path can vary based on how API ML is configured at your site:
To access that API ML instance, create a service profile (or issue a command) with the --base-path
value of api/v1 . Your service profile uses the token and credentials stored in your default base profile.
Commands issued with this profile are routed through the layer to access an appropriate z/OSMF instance.

Accessing multiple services with SSO

If multiple services are registered to the API Mediation Layer at your site, Zowe CLI lets you access the
services with Single Sign-on (SSO). Log in once to conveniently access all available services.
When you are logged-in, supply the --base-path option on commands for each service. Ensure that you
do not provide username, password, host, or port directly on your service commands or profiles. Supplying
those options causes the CLI to ignore the token in your base profile and directly access the service. You
might need to remove those options from existing profiles to use SSO.
For information about registering an API service at your site, see Developing for API Mediation Layer.

Accessing services through SSO + one service not through

APIML
There might be a scenario where you log in to API ML with SSO, but you also want access a different service
directly (not through API ML).
To access the SSO-enabled services, log in and issue commands with the --base-path and --base-
profile options. The token from your base profile is used for authentication. Remember, your command
or service profile must not contain username, password, host, or port.
To access the other service directly (circumvent API ML), supply all connection information (username,
password, host, and port) on a command or service profile. When you explicitly supply username and
password in a command or service profile, the CLI always uses that connection information instead of the
API ML token.

Accessing services through SSO + one service through API

ML but not SSO
You might want to access multiple services with SSO, but also access a service through API ML that is not
SSO-enabled.
To perform SSO for the first set of services, log in to API ML and supply the --base-path and --base-
profile on commands. For more information, see Accessing multiple services with SSO.

To access the service that is not SSO-enabled, explicitly provide your username and password when you
issue commands. Using the --base-path option ensures that the request is routed to API ML, but the
username and password that you provide overrides the credentials in your base profile. This lets you sign in
to the individual service.
Working with certificates
Version: v2.0.x LTS

Certificates authorize communication between a server and client, such as z/OSMF and Zowe CLI. The client
CLI must "trust" the server to successfully issue commands. Use one of the following methods to let the CLI
communicate with the server.

Configure certificates signed by a Certificate Authority

(CA)
System Administrators can configure the server with a certificate signed by a Certificate Authority (CA)
trusted by Mozilla. When a CA trusted by Mozilla exists in the certificate chain, the CLI automatically
recognizes the server and authorizes the connection. Related information:
Using certificates with z/OS client/server applications in the IBM Knowledge Center.
Configuring the z/OSMF key ring and certificate in the IBM Knowledge Center.
Certificate management in Zowe API Mediation Layer
Mozilla Included CA Certificate List

Extend trusted certificates on client

If your organization uses self-signed certificates in the certificate chain (rather than a CA trusted by Mozilla),
you can download the certificate to your computer add it to the local list of trusted certificates. Provide the
certificate locally using the NODE_EXTRA_CA_CERTS environment variable. Organizations might want to
configure all client computers to trust the self-signed certificate. This blog post outlines the process for
using environment variables to trust the self-signed certificate.

Bypass certificate requirement

If you do not have server certificates configured at your site, or you want to trust a known self-signed
certificate, you can append the --reject-unauthorized false flag to your CLI commands. Setting
the --reject-unauthorized flag to false rejects self-signed certificates and essentially bypasses
the certificate requirement.
Important! Understand the security implications of accepting self-signed certificates at your site before you
use this command.
Example:
Completing advanced tasks
Version: v2.0.x LTS

This section describes how to use Zowe CLI using its advanced capabilities.

Using environment variables

You can define environment variables to execute commands more efficiently. Store a value such as your
password in an environment variable, then issue commands without specifying your password every time.
The term environment can refer to your operating system, container environment, or automation server such
as Jenkins. You might want to assign a variable in the following scenarios:
Store a value that is commonly used.
For example, you might want to specify your mainframe username as an environment variable. Now you
can issue commands and omit the --user option, and Zowe CLI automatically uses the value that you
defined in the environment variable.
Override a value in existing profiles.
For example, you might want to override a value that you previously defined in multiple profiles to avoid
recreating each profile. Specify the new value as a variable to override the value in profiles.
Secure credentials in an automation server or container You can set environment variables for use in
scripts that run in your CI/CD pipeline. For example, can define environment variables in Jenkins so that
your password is not seen in plaintext in logs. You can also define sensitive information in the Jenkins
secure credential store.

Formatting environment variables

Transform an option into the proper format for a Zowe CLI environment variable, then define a value to the
variable. Transform option names according to the following rules:
Prefix environment variables with ZOWE_OPT_ .
Convert lowercase letters in arguments/options to uppercase letters.
Convert hyphens in arguments/options to underscores.
Tip: Refer to your operating system documentation for information about how to set and get environment
variables. The procedure varies between Windows, Mac, and various versions of Linux.
Examples:
The following table provides examples of CLI options and the corresponding environment variable to which
you can define a value:
Command Environment Variable Use Case
Option
Define your mainframe username to an
--user ZOWE_OPT_USER environment variable to avoid specifying
it on all commands or profiles.
Define a value of true to the --
--reject- reject-unauthorized flag when you
unauthorized
ZOWE_OPT_REJECT_UNAUTHORIZED
always require the flag and do not want
to specify it on all commands or profiles.

Setting environment variables in an automation server

You can use environment variables in an automation server, such as Jenkins, to write more efficient scripts
and make use of secure credential storage. Automation tools such as Jenkins automation server usually
provide a mechanism for securely storing configuration (for example, credentials). In Jenkins, you can use
withCredentials to expose credentials as an environment variable (ENV) or Groovy variable.
You can either set environment variables using the SET command within your scripts, or navigate to
Manage Jenkins > Configure System > Global Properties and define an environment variable in the
Jenkins GUI. For example:
Using the prompt feature
Zowe CLI has a command-line "prompt" feature that asks you to provide required option values. The CLI
always prompts for host, port, username, and password if you do not supply them in commands or profile
configuration.
You can also manually enable the prompt for any option. This is helpful to mask sensitive information on the
screen while you type. You can enable a one-time prompt, or choose to always prompt for a particular
option.
Enable prompt
Enable one-time prompting as needed.
. Begin typing a command.
. For the option(s) that you want to mask, insert the value "PROMPT*" . For example, prompt for your
password:
The CLI prompts you to enter a value for the --password field.
. Enter a value to complete the command.
Tip: Enter the value carefully. The backspace key does not work in prompt mode.
Always prompt
You can configure your environment so that the CLI always prompts for a particular option, such as --
password .

To enable the feature, set an environment variable named ZOWE_OPT_PASSWORD with the value
"PROMPT*" . With the environment variable set, the CLI automatically enables the prompt when you omit a
required --password value.
Tip The procedure for setting environment variables is dependent on your operating systems. Refer to
documentation for your OS to learn about setting environment variables.
Change the keyword for prompt
The default keyword that enables prompting is "PROMPT*" . You might want to change the keyword if there
is a chance that "PROMPT*" could exist as a valid value for the field. For example, if you mask the data-
set argument and are working with real mainframe data sets that begin with the characters "PROMPT*" .

To configure the keyword, choose a new value. Then define the value to to the environment variable on your
computer named ZOWE_PROMPT_PHRASE .

Writing scripts
You can combine multiple Zowe CLI commands in bash or shell scripts to automate actions on z/OS.
Implement scripts to enhance your development workflow, automate repetitive test or build tasks, and
orchestrate mainframe actions from continuous integration/continuous deployment (CI/CD) tools such as
Jenkins or TravisCI.
Note: The type of script that you write depends on the programming languages that you use and the
environment where the script is executed. The following is a general guide to Zowe CLI scripts. Refer to
third-party documentation to learn more about scripting in general.
Follow these steps:
. Create a new file on your computer with the extension .sh. For example, testScript.sh .
Note: On Mac and Linux, an extension is not required. To make the file executable, issue the command
chmod u+x testScript .
 . (Mac and Linux only) At the top of the file, specify the interpreter that your script requires. For
example, type #!/bin/sh or #!/bin/bash .
Note: The command terminal that you use to execute the script depends on what you specify at the top
of your script. Bash scripts require a bash interpreter (bash terminal), while shell scripts can be run from
any terminal.
. Write a script using a series of Zowe CLI commands.
Tip: You can incorporate commands from other command-line tools in the same script. You might
choose to "pipe" the output of one command into another command.
. From the appropriate command terminal, issue a command to execute the script. The command you
use to execute script varies by operating system.
The script runs and prints the output in your terminal. You can run scripts manually, or include them in your
automated testing and delivery pipelines.
Sample script library
Refer to the Zowe CLI Sample Scripts repository for examples that cover a wide range of scripting languages
and use cases.
Example: Clean up Temporary Data Sets
The script in this example lists specified data sets, then loops through the list of data sets and deletes each
file. You can use a similar script to clean up temporary data sets after use.
Note: Run this script from a bash terminal.
Example: Submit Jobs and Save Spool Output
The script in this example submits a job, waits for the job to enter output status, and saves the spool files to
local files on your computer.
Note: Run this script from a bash terminal.
Extending Zowe CLI
Version: v2.0.x LTS

You can install plug-ins to extend the capabilities of Zowe™ CLI. Plug-ins CLI to third-party applications are
also available, such as Visual Studio Code Extension for Zowe (powered by Zowe CLI). Plug-ins add
functionality to the product in the form of new command groups, actions, objects, and options.
Important! Plug-ins can gain control of your CLI application legitimately during the execution of every
command. Install third-party plug-ins at your own risk. We make no warranties regarding the use of third-
party plug-ins.
Install Zowe CLI plug-ins
IBM® CICS Plug-in for Zowe CLI
IBM® Db2® Database Plug-in for Zowe CLI
IBM® z/OS FTP Plug-in for Zowe CLI
IBM® IMS™ Plug-in for Zowe CLI
IBM® MQ Plug-in for Zowe CLI
Visual Studio Code (VSCode) Extension for Zowe
Software requirements for Zowe CLI plug-ins
Version: v2.0.x LTS

Before you use Zowe™ CLI plug-ins, complete the following steps:
Important! You can perform the required configurations for the plug-ins that you want to use before or
after you install the plug-ins. However, if you do not perform the required configurations, the plug-ins will
not function as designed.
Plug-in Required Configurations
Ensure that IBM CICS Transaction Server v5.2 or later is installed and running in
IBM CICS your mainframe environment
Plug-in for IBM CICS Management Client Interface (CMCI) is configured and running in your
Zowe CLI CICS region.

IBM Db2 Download and prepare the ODBC driver (required for only package installations)
Database and address the licensing requirements. Perform this task before you install the
Plug-in for plug-in.
Zowe CLI (MacOS) Download and Install Xcode.

IBM z/OS FTP Ensure that z/OS FTP service is enabled and configured with
JESINTERFACELEVEL = 2.
Plug-in for
Zowe CLI FTP over SSL is recommended.

Ensure that IBM® IMS™ v14.1.0 or later is installed and running in your mainframe
environment.
IBM IMS Plug- Configure IBM® IMS™ Connect.
in for Zowe CLI Configure IBM IMS Operations APIs to enable communication between the CLI
and the IMS instance.
 Plug-in Required Configurations
Ensure that IBM® MQ™ v9.1.0 or later is installed and running in your mainframe
IBM MQ Plug- environment. Please read this blog for more information: Exposing the MQ REST
in for Zowe CLI API via the Zowe API Mediation Layer

Visual Studio Node.js V8.0 or later

Code Access to z/OSMF; at least one profile is configured
Extension for Configure TSO/E address space services, z/OS data set, file REST interface, and
Zowe z/OS jobs REST interface. For more information, see z/OS Requirements.

Important! You can perform the required configurations for the plug-ins that you want to use before or
after you install the plug-ins. However, if you do not perform the required configurations, the plug-ins will
not function as designed.
Installing Zowe CLI plug-ins
Version: v2.0.x LTS

Use commands in the plugins command group to install and manage Zowe™ CLI plug-ins.
Important! Plug-ins can gain control of your CLI application legitimately during the execution of commands.
Install third-party plug-ins at your own risk. We make no warranties regarding the use of third-party plug-ins.
You can install the following Zowe plug-ins:
IBM® CICS® Plug-in for Zowe CLI
IBM® Db2® Plug-in for Zowe CLI
Third-party Zowe Conformant Plug-ins
Use either of the following methods to install plug-ins:
Install from an online NPM registry. Use this method when your computer can access the Internet.
For more information, see Installing plug-ins from an online registry.
Install from a local package. With this method, you download and install the plug-ins from a bundled set
of .tgz files. Use this method when your computer cannot access the Internet.
For more information, see Installing plug-ins from a local package.

Installing plug-ins from an online registry

Install Zowe CLI plug-ins using npm commands on Windows, Mac, and Linux. The procedures in this article
assume that you previously installed the core CLI.
Follow these steps:
. Meet the software requirements for each plug-in that you install.
. Issue the following command to install a plug-in from public npm:
Note: Replace <my-plugin> with the installation command syntax in the following table:
 Plug-in Syntax
IBM CICS Plug-in for Zowe CLI @zowe/cics-for-zowe-cli@zowe-v2-lts

IBM Db2 Plug-in for Zowe CLI @zowe/db2-for-zowe-cli@zowe-v2-lts

IBM z/OS FTP Plug-in for Zowe CLI @zowe/zos-ftp-for-zowe-cli@zowe-v2-lts

IBM IMS Plug-in for Zowe CLI @zowe/ims-for-zowe-cli@zowe-v2-lts

IBM MQ Plug-in for Zowe CLI @zowe/mq-for-zowe-cli@zowe-v2-lts

. (Optional) Issue the following command to install two or more plug-ins using one command. Separate
the <my-plugin> names with one space.
Note: The IBM Db2 Plug-in for Zowe CLI requires additional licensing and ODBC driver configurations. If
you installed the DB2 plug-in, see IBM Db2 Plug-in for Zowe CLI.
You installed Zowe CLI plug-ins.

Installing plug-ins from a local package

Install plug-ins from a local package on any computer that has limited or no access to the Internet. The
procedure assumes that you previously installed the core CLI.
Follow these steps:
. Meet the software requirements for each plug-in that you want to install.
. Obtain the installation files.
From the Zowe Download website, click Download Zowe CLI to download the Zowe CLI installation
package named zowe-cli-package-*v*.*r*.*m*.zip to your computer.
Note: v indicates the version, r indicates the release number, and m indicates the modification
number
 . Open a command-line window, such as Windows Command Prompt. Browse to the directory where you
downloaded the Zowe CLI installation package (.zip file). Issue the following command, or use your
preferred method to unzip the files:
Example:
By default, the unzip command extracts the contents of the zip file to the directory where you
downloaded the .zip file. You can extract the contents of the zip file to your preferred location.
. Issue the following command against the extracted directory to install each available plug-in:
Replace <my-plugin> with the .tgz file name listed in the following table:
Plug-in .tgz File Name
IBM CICS Plug-in for Zowe CLI cics-for-zowe-cli.tgz

IBM Db2 Plug-in for Zowe CLI db2-for-zowe-cli.tgz

IBM z/OS FTP Plug-in for Zowe CLI zos-ftp-for-zowe-cli.tgz

IBM IMS Plug-in for Zowe CLI ims-for-zowe-cli.tgz

IBM MQ Plug-in for Zowe CLI mq-for-zowe-cli.tgz

You installed Zowe CLI plug-ins.

Validating plug-ins
Issue the plug-in validation command to run tests against all plug-ins (or against a plug-in that you specify)
to verify that the plug-ins integrate properly with Zowe CLI. The tests confirm that the plug-in does not
conflict with existing command groups in the base application. The command response provides you with
details or error messages about how the plug-ins integrate with Zowe CLI.
The validate command has the following syntax:
[plugin] (Optional) Specifies the name of the plug-in that you want to validate. If you do not specify
a plug-in name, the command validates all installed plug-ins. The name of the plug-in is not always the
 same as the name of the NPM package.
Plug-in Syntax
IBM CICS Plug-in for Zowe CLI @zowe/cics-for-zowe-cli

IBM Db2 Plug-in for Zowe CLI @zowe/db2-for-zowe-cli

IBM z/OS FTP Plug-in for Zowe CLI @zowe/zos-ftp-for-zowe-cli

IBM IMS Plug-in for Zowe CLI @zowe/ims-for-zowe-cli

IBM MQ Plug-in for Zowe CLI @zowe/mq-for-zowe-cli

Examples: Validate plug-ins

The following example illustrates the syntax to use to validate the IBM CICS Plug-in for Zowe CLI:
The following example illustrates the syntax to use to validate all installed plug-ins:

Updating plug-ins
You can update Zowe CLI plug-ins from an online registry or from a local package.
Update plug-ins from an online registry
Issue the update command to install the latest stable version or a specific version of a plug-in that you
installed previously. The update command has the following syntax:
[plugin...]
Specifies the name of an installed plug-in that you want to update. The name of the plug-in is not
always the same as the name of the NPM package. You can use npm semantic versioning to specify a
plug-in version to which to update. For more information, see npm semver.
[--registry \<registry>\]

(Optional) Specifies a registry URL that is different from the registry URL of the original installation.
Examples: Update plug-ins
The following example illustrates the syntax to use to update an installed plug-in to the latest version:
The following example illustrates the syntax to use to update a plug-in to a specific version:
Update plug-ins from a local package
You can update plug-ins from a local package. You acquire the media from the Zowe Download website and
update the plug-ins using the zowe plugins install command.
To update plug-ins from a local package, follow the steps described in Installing plug-ins from a local
package.

Uninstall Plug-ins
Issue the uninstall command to uninstall plug-ins from Zowe CLI. After the uninstall process completes
successfully, the product no longer contains the plug-in configuration.
The uninstall command contains the following syntax:
[plugin]

Specifies the name of the plug-in that you want to uninstall.

The following table describes the uninstallation command syntax for each plug-in:
Plug-in Syntax
IBM CICS Plug-in for Zowe CLI @zowe/cics-for-zowe-cli

IBM Db2 Plug-in for Zowe CLI @zowe/db2-for-zowe-cli

IBM z/OS FTP Plug-in for Zowe CLI @zowe/zos-ftp-for-zowe-cli

IBM IMS Plug-in for Zowe CLI @zowe/ims-for-zowe-cli

IBM MQ Plug-in for Zowe CLI @zowe/mq-for-zowe-cli

Example:
The following example illustrates the command to uninstall the CICS plug-in:
IBM® CICS® Plug-in for Zowe CLI
Version: v2.0.x LTS

The IBM® CICS® Plug-in for Zowe™ CLI lets you extend Zowe CLI to interact with CICS programs and
transactions. The plug-in uses the IBM CICS® Management Client Interface (CMCI) API to achieve the
interaction with CICS. For more information, see CICS management client interface on the IBM Knowledge
Center.
Use Cases
Commands
Software requirements
Installing
Creating a user profile

Use cases
As an application developer, you can use the plug-in to perform the following tasks:
Deploy code changes to CICS applications that were developed with COBOL.
Deploy changes to CICS regions for testing or delivery. See the define command for an example of how
you can define programs to CICS to assist with testing and delivery.
Automate CICS interaction steps in your CI/CD pipeline with Jenkins Automation Server or TravisCI.
Deploy build artifacts to CICS regions.
Alter, copy, define, delete, discard, and install CICS resources and resource definitions.

Commands
For detailed documentation on commands, actions, and options available in this plug-in, see our Web Help.
It is available for download in three formats: a PDF document, an interactive online version, and a ZIP file
containing the HTML for the online version.
Browse Online
Download (ZIP)
Download (PDF)
Software requirements
Before you install the plug-in, meet the software requirements in Software requirements for Zowe CLI plug-
ins.

Installing
Use one of the following methods to install or update the plug-in:
Installing plug-ins from an online registry
Installing plug-ins from a local package

Creating a user profile

You can set up a CICS profile to avoid typing your connection details on every command. The profile
contains your host, port, username, and password for the CMCI instance of your choice. You can create
multiple profiles and switch between them if necessary. Issue the following command to create a cics profile:
The plug-in uses HTTPS by default. Use the optional flag --protocol http to override the default with
HTTP.
Note: For more information, issue the command zowe profiles create cics --help
IBM® Db2® Database Plug-in for Zowe CLI
Version: v2.0.x LTS

The IBM® Db2® Database Plug-in for Zowe™ CLI lets you interact with Db2 for z/OS to perform tasks
through Zowe CLI and integrate with modern development tools. The plug-in also lets you interact with Db2
to advance continuous integration and to validate product quality and stability.
Zowe CLI Plug-in for IBM Db2 Database lets you execute SQL statements against a Db2 region, export a
Db2 table, and call a stored procedure. The plug-in also exposes its API so that the plug-in can be used
directly in other products.

Use cases
As an application developer, you can use Zowe CLI Plug-in for IBM DB2 Database to perform the following
tasks:
Execute SQL and interact with databases.
Execute a file with SQL statements.
Export tables to a local file on your computer in SQL format.
Call a stored procedure and pass parameters.

Commands
For detailed documentation on commands, actions, and options available in this plug-in, see our Web Help.
It is available for download in three formats: a PDF document, an interactive online version, and a ZIP file
containing the HTML for the online version.
Browse Online
Download (ZIP)
Download (PDF)

Software requirements
Before you install the plug-in, meet the software requirements in Software requirements for Zowe CLI plug-
ins.
Installing
Use one of the following methods to install the the Zowe CLI Plug-in for IBM Db2 Database:
Install from an online registry
Install from a local package
Installing from an online registry
Complete the following steps if you installed Zowe CLI from online registry:
. If you are installing the plug-in on an Apple computer that contains an M1 (or later architecture)
processor, complete the steps in M1 processor installation. If not, continue to Step 2.
. Open a command line window and issue the following command:
. Address the license requirements to begin using the plug-in.
Installing from a local package
Follow these procedures if you downloaded the Zowe installation package:
Downloading the ODBC driver
Download the ODBC driver before you install the Db2 plug-in.
Follow these steps:
. If you are installing the plug-in on a Apple computer that contains an M1 (or later architecture)
processor, complete the steps in M1 processor installation. If not, continue to Step 2.
. Download the ODBC CLI Driver (Darwin x64). Use the table within the download URL to select the
correct CLI Driver for your platform and architecture.
. Create a new directory named odbc_cli on your computer. Remember the path to the new directory.
You will need to provide the full path to this directory immediately before you install the Db2 plug-in.
. Place the ODBC driver in the odbc_cli folder. Do not extract the ODBC driver.
You downloaded and prepared to use the ODBC driver successfully. Proceed to install the plug-in to Zowe
CLI.
Installing Xcode on MacOS
To install the Db2 CLI plug-in on MacOS, you need the command line tools, which can be obtained by
installing Xcode from the App Store.
Note: On some versions of MacOS, you may receive the error xcrun: error: invalid active
developer path as shown below:

If this occurs, a manual refresh of the command line tools is required by running the following commands:
Installing the plug-in
Now that the Db2 ODBC CLI driver is downloaded, set the IBM_DB_INSTALLER_URL environment variable
and install the Db2 plug-in to Zowe CLI.
Follow these steps:
. Open a command line window and change the directory to the location where you extracted the zowe-
cli-bundle.zip file. If you do not have the zowe-cli-bundle.zip file, see the topic Install
Zowe CLI from local package in Installing Zowe CLI for information about how to obtain and extract it.
. From a command line window, set the IBM_DB_INSTALLER_URL environment variable by issuing the
following command:
Windows operating systems:
Linux and Mac operating systems:
For example, if you downloaded the Windows x64 driver (ntx64_odbc_cli.zip) to C:\odbc_cli, you would
issue the following command:
. Issue the following command to install the plug-in:
. Address the license requirements to begin using the plug-in.

Addressing the license requirement

To successfully connect the Db2 CLI plug-in to a database on z/OS, a license needs to be present either on
the client where the Zowe CLI is executed from, or else on z/OS. If you do not have a license configured
when you execute Db2 CLI commands, you will receive an error SQL1598N , for example:
Server-side license
You can execute the utility db2connectactivate on z/OS to enable a Db2 database to accept client
requests. For more information, see db2connectactivate - Server license activation utility. This avoids having
to apply the Db2 Connect license on each database client that connects directly to the server. It is also the
preferred approach to enabling users of the Zowe Db2 CLI because it avoids individual client license
distribution and configuration.
Client-side license
If the utility db2connectactivate has not been executed against the Db2 database that your profile is
connecting to, then it is possible to obtain the license file db2consv_zs.lic from a copy of DB2 Connect
and use this for client configuration. This will need to be done separately for each client PC.
. Locate your client copy of the Db2 license file db2consv_zs.lic .
Note: The license must be of version 11.5 if the Db2 server is not db2connectactivated . You can
buy a db2connect license from IBM. The connectivity can be enabled either on server using
db2connectactivate utility or on client using client side license file. To know more about DB2 license and
purchasing cost, please contact IBM Customer Support.
. Copy your Db2 license file db2consv_za.lic and place it in the following directory.
Tip: By default, <zowe_home> is set to ~/.zowe on *UNIX Aand Mac systems, and C:\Users\
<Your_User>\.zowe on Windows systems.

After the license is copied, you can use the Db2 plugin functionality.

Creating a user profile

Before you start using the IBM Db2 plug-in, create a profile with details of the Db2 system you're connecting
to.
The Db2 server host name
 The Db2 server port number
The database name (you can also use the location)
To get the Db2 system information, the following two methods can be used.
Issue the command -DISPLAY DDF in the Db2 SPUFI command on z/OS
or
View the JES spool for the MSTR job for the Db2 subsystem and search for the message DSNL004I .
For example, for the database DI2E the JES job DI2EMSTR will have an entry with similar to:
The DOMAIN is used for the <hostname>, the TCPPORT for the <port> and the LOCATION for the
<database> in the zowe create profile command.
In addition to the host, port and database you'll need
The user name
The password
If your Db2 systems use a secure connection, you can also provide an SSL/TSL certificate file.
To create a db2 team profile in Zowe CLI, open the zowe.config.json file and specify the properties for
the port and database :
SQL0805N: Database BIND
To be able to run remote SQL commands against a Db2 database, you must invoke a BIND command
against it. If the BIND command is not run, you will see an error that contains SQL0805N similar to the log
below:
If you receive this error, a user with DBADM authority must run the BIND command. This will typically be
done by a Db2 System Programmer. More information can be found in the Db2 product documentation and
The Bind process.
M1 processor installation
Version: v2.0.x LTS

The IBM ODBC DB2 driver functions only on MacOS x86_64 architecture.
Use the following steps to configure an M1 (or later architecture) processor to behave as MacOS x86_64
architecture so that it can communicate with the IBM ODBC DB2 driver.
. Install Rosetta. Open a terminal window and issue the following command:
. Modify ~/.zshrc to contain the following syntax:
. Source the new file by issuing the following command:
. Switch to the x86_64 architecture by issuing the following command:
. Reinstall Zowe CLI.
. After you complete these steps, do one of the following:
If you are installing the plug-in from an online registry, continue with Step 2 in Install from an online
registry.
If you are installing the plug-in from a local package, continue with Step 2 in Installing from a local
package.
Important! You must issue the intel command every time that you open a new terminal window to help
ensure that Zowe CLI, Secure Credential Storage and the DB2 plug-in function properly on x86_64
architecture. Also, issue the command before you issue Zowe CLI commands.
IBM® z/OS FTP Plug-in for Zowe CLI
Version: v2.0.x LTS

The IBM® z/OS FTP Plug-in for Zowe™ CLI lets you extend Zowe CLI to access z/OS datasets, USS files, and
submit JCL. The plug-in uses the z/OS FTP service to achieve the interaction with z/OS.

Use cases
As a z/OS user, you can use the plug-in to perform the following tasks:
List, view, rename, and download z/OS datasets or USS files.
Upload local files or stdin to z/OS datasets or USS files.
List, view, and download job status or job spool files.
Delete a z/OS dataset, USS file, or job.

Commands
For detailed documentation on commands, actions, and options available in this plug-in, see our Web Help.
It is available for download in three formats: a PDF document, an interactive online version, and a ZIP file
containing the HTML for the online version.
Browse Online
Download (ZIP)
Download (PDF)

Software requirements
Before you install the plug-in, meet the software requirements in Software requirements for Zowe CLI plug-
ins.

Installing
Use one of the following methods to install or update the plug-in:
 Installing plug-ins from an online registry
Installing plug-ins from a local package

Creating a user profile

You can create a zftp user profile to avoid typing your connection details on every command. A zftp
profile contains the host, port, username, and password for the z/OS instance to which you want to connect.
You can create multiple profiles and switch between them as needed.
Issue the following command:
Note: There is an option named --secure-ftp that is set to true by default. If FTPS (FTP over SSL) is
not enabled in z/OS FTP service, we recommend using --secure-ftp false . FTPS is not equivalent to
SFTP (FTP over SSH).
Note: For more information about the syntax, actions, and options, for a profiles create command, open
Zowe CLI and issue the following command:
IBM® IMS™ Plug-in for Zowe CLI
Version: v2.0.x LTS

The IBM IMS Plug-in for Zowe CLI lets you extend Zowe CLI such that it can interact with IMS resources
(regions, programs and transactions). You can use the plug-in to start, stop, and query regions and start,
stop, query, and update programs and transactions.
Note: For more information about IMS, see IBM Information Management System (IMS) on the IBM
Knowledge Center.

Use cases
As an application developer or DevOps administrator, you can use IBM IMS Plug-in for Zowe CLI to perform
the following tasks:
Refresh IMS transactions, programs, and dependent IMS regions.
Deploy application code into IMS production or test systems.
Write scripts to automate IMS actions that you traditionally perform using ISPF editors, TSO, and SPOC.

Commands
For detailed documentation on commands, actions, and options available in this plug-in, see our Web Help.
It is available for download in three formats: a PDF document, an interactive online version, and a ZIP file
containing the HTML for the online version.
Browse Online
Download (ZIP)
Download (PDF)

Software requirements
Before you install the plug-in, meet the software requirements in Software requirements for Zowe CLI plug-
ins.
Installing
Use one of the following methods to install or update the plug-in:
Installing plug-ins from an online registry
Installing plug-ins from a local package

Creating user profiles

You can set up an ims profile to retain your credentials, host, and port name. You can create multiple
profiles and switch between them as needed. Issue the following command to create an ims profile:
Example: Setting up an IMS profile
The following example creates an ims profile named 'ims123' to connect to IMS APIs at host zos123 and port
1490. The name of the IMS plex in this example is 'PLEX1' and the IMS region we want to communicate with
has a host of zos124 and a port of 1491:
Note: For more information, issue the command zowe profiles create ims-profile --help .
IBM® MQ Plug-in for Zowe CLI
Version: v2.0.x LTS

The IBM MQ Plug-in for Zowe CLI lets you issue MQSC commands to a queue manager. MQSC commands
let you to perform administration tasks. For example, you can define, alter, or delete a local queue object.
Note: For more information about MQSC commands and the corresponding syntax, see MQSC commands
on the IBM Knowledge Center.

Use cases
You can use the plug-in to execute MQSC Commands. With MQSC commands you can manage queue
manager objects (including the queue manager itself), queues, process definitions, channels, client
connection channels, listeners, services, namelists, clusters, and authentication information objects.

Using IBM MQ plug-in commands

For detailed documentation on commands, actions, and options available in this plug-in, see our Web Help.
It is available for download in three formats: a PDF document, an interactive online version, and a ZIP file
containing the HTML for the online version.
Browse Online
Download (ZIP)
Download (PDF)

Software requirements
Before you install the plug-in, meet the software requirements in Software requirements for Zowe CLI plug-
ins.

Installing
Use one of the following methods to install or update the plug-in:
Installing plug-ins from an online registry
 Installing plug-ins from a local package

Creating a user profile

You can create an mq user profile to avoid typing your connection details on every command. An mq
profile contains the host, port, username, and password for the MQ Rest API server of your choice. You can
create multiple profiles and switch between them as needed.
Follow these steps:
. Create an mq profile:
The result of the command displays as a success or failure message. You can use your profile when you
issue commands in the mq command group.
Tip: For more information about the syntax, actions, and options, for a profiles create command, open Zowe
CLI and issue the following command:
Visual Studio Code (VS Code) Extension for
Version: v2.0.x LTS

Zowe
chat on Slack

The Zowe Explorer extension for Visual Studio Code (VS Code) modernizes the way developers and system
administrators interact with z/OS mainframes, and lets you interact with data sets, USS files and jobs. Install
the extension directly to VSCode to enable the extension within the GUI. Working with data sets and USS
files from VSCode can be more convenient than using 3270 emulators, and complements your Zowe CLI
experience. The extension provides the following benefits:
Enables you to create, modify, rename, copy, and upload data sets directly to a z/OS mainframe.
Enables you to create, modify, rename, and upload USS files directly to a z/OS mainframe.
Provides a more streamlined way to access data sets, USS files and jobs.
Lets you create, edit, and delete Zowe CLI zosmf compatible profiles.
Lets you use the Secure Credential Store plug-in to store your credentials securely in the settings.
Note: Zowe Explorer is a subcomponent of Zowe. The extension demonstrates the potential for plug-ins
powered by Zowe.

Software Requirements
Ensure that you meet the following prerequisites before you use the extension:
Get access to z/OSMF.
Install Node.js v8.0 or later.
Install VSCode.
Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST
interface. For more information, see z/OS Requirements.
Create one Zowe CLI zosmf profile so that the extension can communicate with the mainframe.
Profile notes:
You can use your existing Zowe CLI zosmf profiles that are created with the Zowe CLI v.2.0.0 or later.
 Zowe CLI zosmf profiles that are created in Zowe Explorer can be interchangeably used in the Zowe
CLI.
Optionally, you can continue using Zowe CLI V1 profiles with Zowe Explorer. For more information, see
instert link here.

Installing
Use the following steps to install Zowe Explorer:
. Address the software requirements.
. Open VSCode, and navigate to the Extensions tab on the left-hand side of the UI.
. Type Zowe Explorer in the search field.
Zowe Explorer appears in the list of extensions in the left-hand panel.
. Click the green Install button to install the extension.
. Restart VSCode.
The extension is now installed and available for use.
Note: For information about how to install the extension from a VSIX file and run system tests on the
extension, see the Developer README.
You can also watch the following videos to learn how to get started with Zowe Explorer, and work with data
sets.
Configuration
Configure Zowe Explorer in the settings file of the extension. To access the extension settings, navigate to
Manage (the gear icon) > Settings, then select Extensions > Zowe Explorer Settings. For example, you
can modify the following settings:
Data set creation settings: You can change the default creation settings for various data set types.
Follow these steps:
. Click the Edit in settings.json button under the Data Set, USS or JOBS settings that you want to edit.
. Edit the settings as needed.
. Save the settings.

Set the Temporary Folder Location: You can change the default folder location where temporary files
are stored.
Follow these steps:
i. Click the Edit in settings.json button under the Data Set, USS or JOBS settings that you want to
edit.
ii. Modify the following definition:
where /path/to/directory is the folder location that you specify.
iii. Save the settings.

Relevant Information
In this section you can find useful links and other relevant to Zowe Explorer information that can improve
your experience with the extension.
For information about how to develop for Eclipse Theia, see Theia README.
For information about how to create a VSCode extension for Zowe Explorer, see VSCode extensions for
Zowe Explorer.
Visit the #zowe-explorer channel on Slack for questions and general guidance.
Zowe Explorer Profiles
Version: v2.0.x LTS

After you install Zowe Explorer, you need to have a Zowe Explorer profile to use all functions of the
extension.
Note: You can continue using Zowe V1 profiles with Zowe Explorer V2.

Configuring team profiles

Zowe CLI team profiles simplify profile management by letting you to edit, store, and share mainframe
configuration details in one location. You can use a text editor or an IDE to populate configuration files with
connection details for your mainframe services. By default, your team configuration file is located in the
.zowe home folder, whereas the project-level configuration file is located in the main directory of your
project. You can create profiles that you use globally, given that the names of the globally-used profiles are
different from your other profile names.
Note: A project context takes precedence over global configuration.
Creating team configuration files
Create a team configuration file.
. Navigate to the explorer tree.
. Hover over DATA SETS, USS, or JOBS.
. Click the + icon.
. Select Create a New Team Configuration File.
. Chose either a global configuration file or a project-level configuration file.
. Edit the config file to include the host information and save the file.
. Refresh Zowe Explorer by either clicking the button in the notification message shown after creation,
alt+z , or the Zowe Explorer: Refresh Zowe Explorer command palette option.

Your team configuration file appears either in your .zowe folder if you choose the global configuration file
option, or in your workspace directory if you choose the project-level configuration file option. The
notification message that shows in VS Code after config file creation will include the path of the file created.
Managing profiles
You can edit your project-level or global configuration files.
Follow these steps:
. Right-click on your profile.
. Select the Add, Update, or Delete Profile options to edit the zowe config file in place.
Tip: Use the Intellisense prompts if you need assistance with filling parameters in the file.
. Save the config file.
. Refresh the view by clicking the refresh icon in the Data Sets, USS, or Jobs view.
Alternatively, press F1 to open the command palette, type and execute the Zowe Explorer: Refresh
Zowe Explorer option.
You successfully edited your configuration file.
Sample profile configuration
View the profile configuration sample. In the sample, the default lpar1.zosmf profile will be loaded upon
activation.
You can use the sample to customize your profile configuration file. Ensure that you edit the host and
port values before you work in your environment.

Working with Zowe Explorer profiles

Important! The information in this section applies to only Zowe CLI V1 profiles unless otherwise noted.
Zowe CLI V1 profiles are defined by having one yaml file for each user profile.
You must have a zosmf compatible profile before you can use Zowe Explorer. You can set up a profile to
retain your credentials, host, and port name. In addition, you can create multiple profiles and use them
simultaneously.
Follow these steps:
 . Navigate to the explorer tree.
. Click the + button next to the DATA SETS, USS or JOBS bar.
Note: If you already have a profile, select it from the drop-down menu.
. Select the Create a New Connection to z/OS option.
Note: When you create a new profile, user name and password fields are optional. However, the system
will prompt you to specify your credentials when you use the new profile for the first time.
. Follow the instructions, and enter all required information to complete the profile creation.

You successfully created a Zowe CLI zosmf profile. Now you can use all the functionalities of the
extension.
If you need to edit a profile, right-click the profile and select Update Profile option.

In addition, you can hide a profile from the explorer tree, and permanently delete a profile. When you delete
your profile permanently, the extension erases the profile from the .zowe folder. To hide or delete a profile,
right-click the profile and choose one of the respective options from the list.
Validating profiles
Note: The following information applies to Zowe CLI V1 profiles (one yaml file for each user profile) and
Zowe CLI team profiles (Zowe CLI V2).
Zowe Explorer includes the profile validation feature that helps to ensure that z/OSMF is accessible and
ready for use. If a profile is valid, the profile is active and can be used. By default, the feature is automatically
enabled. You can disable the feature by right-clicking on your profile and selecting the Disable Validation
for Profile option. Alternatively, you can enable or disable the feature for all profiles in the VS Code settings.
Follow these steps:
. Navigate to the VS Code settings.
. Open Zowe Explorer Settings.
. Enable or disable the automatic validation of profiles option.
. Restart VS Code.
Using base profiles and tokens with existing profiles
As a Zowe user, you can leverage the base profile functionality to access multiple services through Single
Sign-on. Base profiles enable you to authenticate using Zowe API Mediation Layer (API ML). You can use
base profiles with more than one service profile. For more information, see Base Profiles.
Before you log in and connect your service profile, ensure that you have Zowe CLI v6.16 or higher installed.
Accessing services through API ML using SSO
Connect your service profile with a base profile and token.
Follow these steps:
. Open Zowe CLI and issue the following command:
. Follow the onscreen instructions to complete the login process.
A local base profile is created that contains your token. For more information about the process, see
Token Management.
. Run Zowe Explorer and click the + icon.
. Select the profile you use with your base profile with the token.
The profile appears in the tree and you can now use this profile to access z/OSMF via the API Mediation
Layer.
For more information, see Integrating with API Mediation Layer.
Logging in to the Authentication Service
If the token for your base profile is no longer valid, you can log in again to get a new token with the Log in to
Authentication Service feature.
Notes:
The feature is only available for base profiles.
The feature supports only API Mediation Layer at the moment. Other extenders may use a different
authentication service.
Follow these steps:
. Open Zowe Explorer.
. Right-click your profile.
. Select the Log in to Authentication Service option.
You will be prompted to enter your username and password beforehand.
The token is stored in the corresponding base profile.
If you do not want to store your token, request from the server to end the session of your token. Use the Log
out from Authentication Service feature to invalidate the token.
Follow these steps:
. Open Zowe Explorer.
. Right-click your profile.
. Select the Log out from Authentication Service option.
Your token has been successfully invalidated.
Configuring Zowe Application Framework
Version: v2.0.x LTS

The Zowe Application ("App") Framework is configured in the Zowe configuration file. Configuration can be
used to change things such as verbosity of logs, the way in which the App server communicates with the
Mediation Layer, how ZSS operates, whether to use HTTPS or AT-TLS, what language the logs should be
set, and many more attributes.
When you install Zowe™, the App Framework is configured as a Mediation Layer client by default. This is
simpler to administer because the App framework servers are accessible externally through a single port:
API ML Gateway port. It is more secure because you can implement stricter browser security policies for
accessing cross-origin content.
You can modify the Zowe App Server and Zowe System Services (ZSS) configuration, as needed, or
configure connections for the Terminal app plugins.

Accessing the App Server

When the server is enabled and given a port within the configuration file, the App server will print a message
ZWED0031I in the log output. At that time, it is ready to accept network communication. When using the API
Mediation Layer (recommended), app-server URLs should be reached from the Gateway, and you should
additionally wait for the message ZWEAM000I for the Gateway to be ready.
When Zowe is ready, the app-server can be found at https://<zowe.externalDomain>:
<components.gateway.port>/zlux/ui/v1

(Not recommended): If the API Mediation Layer is not used, or you need to contact the App server directly,
the ZWED0031I message states which port it is accessible from, though generally it will be the same value
as specified within components.app-server.port . In that case, the server would be available at
https://<zowe.externalDomain>:<components.app-server.port>/

Accessing the Desktop

The app-server should be accessed through the gateway when both are present. When both are
ready, the Desktop can be accessed from the API Mediation Layer Gateway, such as
https://<zowe.externalDomain>:<components.gateway.port>/zlux/ui/v1/ , which will
redirect to https://<zowe.externalDomain>:
<components.gateway.port>/zlux/ui/v1/ZLUX/plugins/org.zowe.zlux.bootstrap/web/inde
x.html

Although you access the App server via the Gateway port, the App server still needs a port assigned to it
which is the value of the components.app-server.port variable in the Zowe configuration file.
(Not recommended): If the mediation layer is not used, the Desktop will be accessible from the App server
directly at /ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html

Accessing ZSS
The zss server should be accessed through the gateway when both are present. When both are ready,
ZSS can be accessed from the API Mediation Layer Gateway, such as
https://<zowe.externalDomain>:<components.gateway.port>/zss/api/v1/

Although you access the ZSS server via the Gateway port, the ZSS server still needs a port assigned to it
which is the value of the components.zss.port variable in the Zowe configuration file.
If the mediation layer is not used, ZSS directly at https://<zowe.externalDomain>:
<components.zss.port>/

Configuration file
app-server configuration
The app-server uses the Zowe server configuration file for customizing server behavior. For a full list of
parameters, requirements, and descriptions, see the json-schema document for the app-server which
describes attributes that can be specified within the configuration file section components.app-server
zss configuration
ZSS shares some parameters in common with the app-server, so you can consult the above json-schema
document to find out which parameters are valid within components.zss of the Zowe configuration file.
However, some parameters within the app-server schema are not used by ZSS, such as the node section.
A ZSS-centric schema will be available soon.

Environment variables
In the latest version of Zowe, instance.env is no longer used. However, some environment variables that
could be specified within v1 can still be set within v2 in the zowe.environments section of the server
configuration file. Environment variables starting with ZWED_ map to values that can be specified within
components.app-server and components.zss so they are redundant, but you can refer to the above
json-schema document to see which values are useful or deprecated.

Configuring the framework as a Mediation Layer client

The App Server and ZSS automatically register to the API Mediation Layer when present. If this is not
desired, registration can disabled by setting the properties components.app-
server.mediationLayer.server.enabled=false for app-server and
components.zss.mediationLayer.enabled=false for ZSS.

Setting up terminal app plugins

Follow these optional steps to configure the default connection to open for the terminal app plugins.
Setting up the TN3270 mainframe terminal app plugin
The file _defaultTN3270.json within the tn3270-ng2 app folder
/config/storageDefaults/sessions/ is deployed to the configuration dataservice when the app-
server runs for the first time. This file is used to tell the terminal what host to connect to by default. If you'd
like to customize this default, you can edit the file directly within the configuration dataservice
<components.app-
server.instanceDir>/org.zowe.terminal.tn3270/sessions/_defaultTN3270.json . Or you
can open the app, customize a session within the UI, click the save icon (floppy icon) and then copy that file
from <components.app-server.usersDir>/<your
user>/org.zowe.terminal.tn3270/sessions/_defaultTN3270.json to <components.app-
server.instanceDir>/org.zowe.terminal.tn3270/sessions/_defaultTN3270.json . Either
way, you will see a file with the following properties:
Setting up the VT Terminal app plugin
The file _defaultVT.json within the vt-ng2 app folder /config/storageDefaults/sessions/
is deployed to the configuration dataservice when the app-server runs for the first time. This file is used to
tell the terminal what host to connect to by default. If you'd like to customize this default, you can edit the file
directly within the configuration dataservice <components.app-
server.instanceDir>/org.zowe.terminal.vt/sessions/_defaultVT.json . Or you can open the
app, customize a session within the UI, click the save icon (floppy icon) and then copy that file from
<components.app-server.usersDir>/<your
user>/org.zowe.terminal.vt/sessions/_defaultVT.json to <components.app-
server.instanceDir>/org.zowe.terminal.vt/sessions/_defaultVT.json . Either way, you will
see a file with the following properties:

Network configuration
Note: The following attributes are to be defined in the Zowe configuration file.
The App Server can be accessed over HTTP and/or HTTPS, provided it has been configured for either.
HTTPS should be used, as HTTP is not secure unless AT-TLS is used. When AT-TLS is used by ZSS,
components.zss.agent.http.attls must be set to true.

HTTPS
Both app-server and zss server components use HTTPS by default, and the port parameters
components.app-server.port and components.zss.port control which port they are accessible
from. However, each have advanced configuration options to control their HTTPS behavior.
The app-server component configuration can be used to customize its HTTPS connection such as
which certificate and ciphers to use, and these parameters are to be set within components.app-
server.node.https as defined within the json-schema file

The zss component configuration can be used to customize its HTTPS connection such as which
certificate and ciphers to use, and these parameters are to be set within components.zss.agent.https
as defined within the json-schema file
HTTP
The app-server can be configured for HTTP via the components.app-server.node.http section
of the Zowe configuration file, as specified within the app-server json-schema file.
The zss server can be configured for HTTP via the components.zss.agent.http section of the Zowe
configuration file, as specified within the zss json-schema file. Note that components.zss.tls must
be set to false for HTTP to take effect, and that components.zss.agent.http.attls must be set to
true for AT-TLS to be recognized correctly.

Configuration Directories
When running, the App Server will access the server's settings and read or modify the contents of its
resource storage. All of this data is stored within a hierarchy of folders which correspond to scopes:
Product: The contents of this folder are not meant to be modified, but used as defaults for a product.
Site: The contents of this folder are intended to be shared across multiple App Server instances,
perhaps on a network drive.
Instance: This folder represents the broadest scope of data within the given App Server instance.
Group: Multiple users can be associated into one group, so that settings are shared among them.
User: When authenticated, users have their own settings and storage for the Apps that they use.
These directories dictate where the Configuration Dataservice will store content. For more information, see
the Configuration Dataservice documentation
Old defaults
Prior to Zowe release 2.0.0, the location of the configuration directories were initialized to be within the
<INSTANCE_DIR> folder unless otherwise customized. 2.0.0 does have backwards compatibility for the
existence of these directories, but <INSTANCE_DIR> folder no longer exists, so they should be migrated
to match the ones specified in the Zowe configuration file.
Folder New Location Old Location

siteDir <zowe.workspaceDirectory>/app-
server/site
<INSTANCE_DIR>/workspace/app-
server/site
 Folder New Location Old Location
insta
instanceDir <zowe.workspaceDirectory>/app- <INSTANCE_DIR>/workspace/app- isn't
server server work
is us

groupsDir <zowe.workspaceDirectory>/app-
server/groups
<INSTANCE_DIR>/workspace/app-
server/groups

usersDir <zowe.workspaceDirectory>/app-
server/users
<INSTANCE_DIR>/workspace/app-
server/users

pluginsDir <zowe.workspaceDirectory>/app-
server/plugins
<INSTANCE_DIR>/workspace/app-
server/plugins

App plugin configuration

The App framework will load plugins from Components such as extensions based upon their enabled status
in Zowe configuration. The server caches knowledge of these plugins in the
<workspaceDirectory>/app-server/plugins folder. This location can be customized with the
components.app-server.pluginsDir variable in the Zowe configuration file.

Logging configuration
For more information, see Logging Utility.
Enabling tracing
To obtain more information about how a server is working, you can enable tracing within the Zowe
configuration file via components.app-server.logLevels or components.zss.logLevels variable. For more
information on all loggers, check out the Extended documentation.
For example:
All settings are optional.
Log files
The app-server and zss will create log files containing processing messages and statistics. The log files are
generated within the log directory specified within the Zowe configuration file ( zowe.logDirectory ).
The filename patterns are:
App Server: <zowe.logDirectory>/appServer-yyyy-mm-dd-hh-mm.log
ZSS: <zowe.logDirectory>/zssServer-yyyy-mm-dd-hh-mm.log
Retaining logs
By default, the last five log files are retained. You can change this by setting environment variables within the
zowe.environments section of the Zowe server configuration file. To specify a different number of logs
to retain, set ZWED_NODE_LOGS_TO_KEEP for app-server logs, or ZWES_LOGS_TO_KEEP for zss logs. For
example, if you set ZWED_NODE_LOGS_TO_KEEP to 10, when the eleventh log is created, the first log is
deleted.
Controlling the logging location
At minimum, the log information for both app-server and zss are written to STDOUT such that messages are
visible in the terminal that starts Zowe and when on z/OS, the STC job log.
By default, both servers additionally log to files and the location of these files can be changed or logging to
them can be disabled. The following environment variables can be used to customize the app-server and
zss log locations by setting the values within the zowe.environments section of the Zowe configuration
file.
ZWED_NODE_LOG_DIR : Overrides the zowe configuration file value of zowe.logDirectory for
app-server, but keeps the default filenames.
ZWES_LOG_DIR : Overrides the zowe configuration file value of zowe.logDirectory for zss, but
keeps the default filenames.
ZWED_NODE_LOG_FILE : Specifies the full path to the file where logs will be written from app-server.
This overrides both ZWED_NODE_LOG_DIR and zowe.logDirectory . If the path is /dev/null
then no log file will be written. This option does not timestamp logs or keep multiple of them.
ZWES_LOG_FILE : Specifies the full path to the file where logs will be written from zss. This overrides
both ZWES_LOG_DIR and zowe.logDirectory . If the path is /dev/null then no log file will be
written. This option does not timestamp logs or keep multiple of them.
If the directory or file specified cannot be created, the server will run (but it might not perform logging
properly).

ZSS configuration
Running ZSS requires a Zowe configuration file configuration that is similar to the one used for the Zowe App
Server (by structure and property names). The attributes that are needed for ZSS (components.zss) at
minimum, are: port, crossMemoryServerName.
By default, ZSS is configured to use HTTPS with the same certificate information and port specification as
the other Zowe services. If you are looking to use AT-TLS instead, then you must set component.zss.tls
variable to false and define component.zss.agent.http section with port, ipAddresses, and attls: true
as shown below
(Recommended) Example of the agent body:
(Not recommended) Unsecure, HTTP example with AT-TLS:
ZSS 64 or 31 bit modes
Two versions of ZSS are included in Zowe, a 64 bit version and a 31 bit version. It is recommended to run the
64 bit version to conserve shared system memory but you must match the ZSS version with the version your
ZSS plugins support. Official Zowe distributions contain plugins that support both 64 bit and 31 bit, but
extensions may only support one or the other.
Verifying which ZSS mode is in use
You can check which version of ZSS you are running by looking at the logs. At startup, the message
ZWES1013I states which mode is being used, for example:
ZWES1013I ZSS Server has started. Version 2.0.0 64-bit

Or
ZWES1013I ZSS Server has started. Version 2.0.0 31-bit

Verifying which ZSS mode plugins support

You can check if a ZSS plugin supports 64 bit or 31 bit ZSS by reading the pluginDefinition.json file of the
plugin. In each component or extension you have, its manifest file will state if there are appFw plugin
entries. In each folder referenced by the appFw section, you will see a pluginDefinition.json file. Within that
file, if you see a section that says type: 'service' , then you can check its ZSS mode support. If the
service has the property libraryName64 , then it supports 64 bit. If it says libraryName31 , then it
supports 31 bit. Both may exist if it supports both. If it instead only contains libraryName , this is
ambigious and deprecated, and most likely that plugin only supports 31 bit ZSS. A plugin only supporting 31
bit ZSS must be recompiled for 64 bit support, so you must contact the developers to accomplish that.
Example: the sample angular app supports both 31 bit and 64 bit zss
Setting ZSS 64 bit or 31 bit mode
You can switch between ZSS 64 bit and 31 bit mode by setting the value
components.zss.agent.64bit to true or false in the Zowe configuration file. The value will not take
effect until next server restart.

Using AT-TLS in the App Framework

By default, both ZSS and the App server use HTTPS regardless of platform. However, some may wish to use
AT-TLS on z/OS as an alternative way to provide HTTPS. In order to do this, the servers must run in HTTP
mode instead, and utilize AT-TLS for HTTPS. The servers should never use HTTP without AT-TLS, it
would be insecure. If you want to use AT-TLS, you must have a basic knowledge of your security product
and you must have Policy Agent configured. For more information on AT-TLS and Policy Agent, see the z/OS
Knowledge Center.
There are a few requirements to working with AT-TLS:
You must have the authority to alter security definitions related to certificate management, and you
must be authorized to work with and update the Policy Agent.
AT-TLS needs a TLS rule and keyring. The next section will cover that information.
Note: Bracketed values below (including the brackets) are variables. Replace them with values relevant to
your organization. Always use the same value when substituting a variable that occurs multiple times.
Creating AT-TLS certificates and keyring using RACF
In the following commands and examples you will create a root CA certificate and a server certificate signed
by it. These will be placed within a keyring which is owned by the user that runs the Zowe server. Note:
These actions can be done for various Zowe servers, but in these examples we set up ZSS for AT-TLS.
You can subsitute ZSS for another server if desired.
Key variables:
Variable Value
[ca_common_name]

[ca_label]

[server_userid]

[server_common_name]

[server_label]

[ring_name]

[output_dataset_name]

Note:
[server_userid] must be the server user ID, such as the STC user.
[server_common_name] must be the z/OS hostname that runs Zowe

. Enter the following RACF command to generate a CA certificate:

. Enter the follow RACF command to generate a server certificate signed by the CA certificate:
. Enter the following RACF commands to create a key ring and connect the certificates to the key ring:
. Enter the following RACF command to refresh the DIGTRING and DIGTCERT classes to activate your
changes:
. Enter the following RACF commands to verify your changes:
 . Enter the following RACF commands to allow the ZSS server to use the certificates. Only issue the
RDEFINE commands if the profiles do not yet exist.
Note: These sample commands use the FACILTY class to manage certificate related authorizations. You can
also use the RDATALIB class, which offers granular control over the authorizations.
. Enter the following RACF command to export the CA certificate to a dataset so it can be imported by the
Zowe server:
Defining the AT-TLS rule
To define the AT-TLS rule, use the sample below to specify values in your AT-TLS Policy Agent Configuration
file:

Using multiple ZIS instances

When you install Zowe, it is ready to be used for 1 instance of each component. However, ZIS can have a
one-to-many relationship with the Zowe webservers, and so you may wish to have more than one copy of
ZIS for testing or to handle different groups of ZIS plugins.
The following steps can be followed to point a Zowe instance at a particular ZIS server.
. Create a copy of the ZIS server. You could run multiple copies of the same code by having different STC
JCLs pointing to the same LOADLIB, or run different copies of ZIS by having JCLs pointing to different
LOADLIBs.
. Edit the JCL of the ZIS STC. In the NAME parameter specify a unique name for the ZIS server, for
example:
Where ZWESIS_MYSRV is the unique name of the new ZIS.
. Start the new ZIS with whatever PROCLIB name was chosen.
. Stop the Zowe instance you wish to point to the ZIS server
. Locate the zowe configuration file for the Zowe instance, and edit the parameter
components.zss.privilegedServerName to match the name of the ZIS STC name chosen, such
as ZWESIS_MYSRV
 . Restart the Zowe instance
. Verify that the new ZIS server is being used by checking for the following messages in the ZWESLSTC
server job log:
ZIS status - Ok (name='ZWESIS_MYSRV ', cmsRC=0, description='Ok',
clientVersion=2)

Controlling access to apps

You can control which apps are accessible (visible) to all Zowe desktop users, and which are accessible only
to individual users. For example, you can make an app that is under development only visible to the team
working on it.
You control access by editing JSON files that list the apps. One file lists the apps all users can see, and you
can create a file for each user. When a user logs into the desktop, Zowe determines the apps that user can
see by concatenating their list with the all users list.
You can also control access to the JSON files. The files are accessible directly on the file system, and since
they are within the configuration dataservice directories, they are also accessible via REST API. We
recommend that only Zowe administrators be allowed to access the file system locations, and you control
that by setting the directories and their contents to have file permissions on z/OS that only allow the Zowe
admin group read & write access. You control who can read and edit the JSON files through the REST API by
controlling who can access the configuration dataservice objects URLs that serve the JSON files.
Enabling RBAC
By default, RBAC is disabled and all authenticated Zowe users can access all dataservices. To enable RBAC,
follow these steps:
. To enable RBAC, set the components.zss.dataserviceAuthentication.rbac and components.app-
server.dataserviceAuthentication.rbac variables to true in the Zowe configuration file.
Controlling app access for all users
Note:
<zowe.runtimeDirectory> variable comes from the Zowe configuration file.
 . Enable RBAC.
. Navigate to the following location:
. Copy the allowedPlugins.json file and paste it in the following location:
. Open the copied allowedPlugins.json file and perform either of the following steps:
To make an app unavailable, delete it from the list of objects.
To make an app available, copy an existing plugin object and specify the app's values in the new
object. Identifier and version attributes are required.
. Restart the app server.
Controlling app access for individual users
. Enable RBAC.
. In the user's ID directory path, in the \pluginStorage directory, create
\org.zowe.zlux.bootstrap\plugins directories. For example:

. In the /plugins directory, create an allowedPlugins.json file. You can use the default
allowedPlugins.json file as a template by copying it from the following location:

. Open the allowedPlugins.json file and specify apps that user can access. For example:
Notes:
Identifier and version attributes are required.
When a user logs in to the desktop, Zowe determines which apps they can see by concatenating
the list of apps available to all users with the apps available to the individual user.
. Restart the app server.

Controlling access to dataservices

To apply role-based access control (RBAC) to dataservice endpoints, you must enable RBAC for Zowe, and
then use a z/OS security product such as RACF to map roles and authorities to the endpoints. After you
apply RBAC, Zowe checks authorities before allowing access to the endpoints.
You can apply access control to Zowe endpoints and to your app endpoints. Zowe provides endpoints for a
set of configuration dataservices and a set of core dataservices. Apps can use configuration endpoints to
store and their own configuration and other data. Administrators can use core endpoints to get status
information from the App Framework and ZSS servers. Any dataservice added as part of an app plugin is a
service dataservice.
Defining the RACF ZOWE class
If you use RACF security, take the following steps define the ZOWE class to the CDT class:
. Make sure that the CDT class is active and RACLISTed.
. In TSO, issue the following command:
If you receive the following message, ignore it:
. In TSO, issue the following command to refresh the CDT class:
. In TSO, issue the following command to activate the ZOWE class:
For more information on RACF security administration, see the IBM Knowledge Center at
https://www.ibm.com/support/knowledgecenter/.
Creating authorization profiles
For users to access endpoints after you enable RBAC, in the ZOWE class you must create System
Authorization Facility (SAF) profiles for each endpoint and give users READ access to those profiles.
Endpoints are identified by URIs in the following format:
/ZLUX/plugins/<plugin_id>/services/<service>/<version>/<path>

For example:
/ZLUX/plugins/org.zowe.foo/services/baz/_current/users/fred

Where the path is /users/fred .

SAF profiles have the following format:
ZLUX.<zowe.rbacProfileIdentifier>.<servicename>.<pluginid_with_underscores>.
<service>.<HTTP_method>.<url_with_forward_slashes_replaced_by_periods>

For example, to issue a POST request to the dataservice endpoint documented above, users must have
READ access to the following profile:
ZLUX.1.SVC.ORG_ZOWE_FOO.BAZ.POST.USERS.FRED

For configuration dataservice endpoint profiles use the service code CFG . For core dataservice endpoints
use COR . For all other dataservice endpoints use SVC .
Creating generic authorization profiles
Some endpoints can generate an unlimited number of URIs. For example, an endpoint that performs a
DELETE action on any file would generate a different URI for each file, and users can create an unlimited
number of files. To apply RBAC to this type of endpoint you must create a generic profile, for example:
ZLUX.1.COR.ORG_ZOWE_FOO.BAZ.DELETE.**

You can create generic profile names using wildcards, such as asterisks (*). For information on generic
profile naming, see IBM documentation.
Configuring basic authorization
The following are recommended for basic authorization:
To give administrators access to everything in Zowe, create the following profile and give them UPDATE
access to it: ZLUX.**
To give non-administrators basic access to the site and product, create the following profile and give
them READ access to it: ZLUX.*.ORG_ZOWE_*
To prevent non-administrators from configuring endpoints at the product and instance levels, create the
following profile and do not give them access to it: ZLUX.1.CFG.**
To give non-administrators all access to user, create the following profile and give them UPDATE access
to it: ZLUX.1.CFG.*.*.USER.**
Endpoint URL length limitations
SAF profiles cannot contain more than 246 characters. If the path section of an endpoint URL is long enough
that the profile name exceeds the limit, the path is trimmed to only include elements that do not exceed the
limit. To avoid this issue, we recommend that appliction developers maintain relatively short endpoint URL
paths.
For information on endpoint URLs, see Dataservice endpoint URL lengths and RBAC

Multi-factor authentication configuration

Multi-factor authentication is an optional feature for Zowe.
As of Zowe version 1.8.0, the Zowe App Framework, Desktop, and all apps present in the SMP/E or
convenience builds support out-of-band MFA by entering an MFA assigned token or passcode into
password field of the Desktop login screen, or by accessing the app-server /auth REST API endpoint.
For a list of compatible MFA products, see Known compatible MFA products.
Session duration and expiration
After successful authentication, a Zowe Desktop session is created by authentication plugins.
The duration of the session is determined by the plugin used. Some plugins are capable of renewing the
session prior to expiration, while others may have a fixed session length.
Zowe is bundled with a few of these plugins:
sso-auth: Uses either ZSS or the API Mediation Layer for authentication, and ZSS for RBAC
authorization. This plugin also supports resetting or changing your password via a ZSS API. Whether
ZSS or API Mediation Layer or both are used for authentication depends upon SSO settings. Starting
with Zowe 1.28.0, SSO is enabled by default such that only API Mediation Layer is called at
authentication time. By default, the Mediation Layer calls z/OSMF to answer the authentication request.
The session created mirrors the z/OSMF session.
trivial-auth: This plugin is used for development and testing, as it always returns true for any function.
It could be used if there were specific services you did not need authentication for, while you wanted
authentication elsewhere.
When a session expires, the credentials used for the initial login are likely to be invalid for re-use, since MFA
credentials are often one-time-use or time-based.
In the Desktop, Apps that you opened prior to expiration will remain open so that your work can resume after
entering new credentials.
Configuration
When you use the default Zowe SMP/E or convenience build configuration, you do not need to change Zowe
to get started with MFA.
To configure Zowe for MFA with a configuration other than the default, take the following steps:
. Choose an App Server security plugin that is compatible with MFA. The sso-auth plugin is compatible.
. Locate the App Server's configuration file in zowe.yaml .
. Edit the configuration file to modify the section components.app-
server.dataserviceAuthentication .

. Set defaultAuthentication to the same category as the plugin of choice, as seen in its
pluginDefinition.json file. For example:
sso-auth: "saf"
trivial-auth: "fallback"
The following is an example configuration for sso-auth , as seen in a default installation of Zowe:

Administering the servers and plugins using an API

The App Server has a REST API to retrieve and edit both the App Server and ZSS server configuration
values, and list, add, update, and delete plugins. Most of the features require RBAC to be enabled and for
your user to have RBAC access to utilize these endpoints. For more information see documentation on how
to use RBAC
The API returns the following information in a JSON response:
API Description

/server (GET) Returns a list of accessible server endpoints for

the Zowe App Server.
 API Description

/server/config (GET) Returns the Zowe App Server configuration

which follows this specification.

/server/log (GET) Returns the contents of the Zowe App Server

log file.

/server/loglevels (GET) Returns the verbosity levels set in the Zowe App
Server logger.
Returns Zowe App Server environment
/server/environment (GET) information, such as the operating system
version, node server version, and process ID.
/server/reload (GET) Reloads the Zowe App Server. Only available in
cluster mode.

/server/agent (GET) Returns a list of accessible server endpoints for

the ZSS server.

/server/agent/config (GET) Returns the ZSS server configuration which

follows this specification.
/server/agent/log (GET) Returns the contents of the ZSS log file.
/server/agent/loglevels (GET) Returns the verbosity levels of the ZSS logger.
/server/agent/environment (GET) Returns ZSS environment information.
/server/logLevels/name/:componentName/level/:level Specify the logger that you are using and a
(POST) verbosity level.

/plugins (GET) Returns a list of all plugins and their

dataservices.
 API Description

/plugins (PUT) Adds a new plugin or upgrades an existing

plugin. Only available in cluster mode (default).

/plugins/:id (DELETE) Deletes a plugin. Only available in cluster mode

(default).
Swagger API documentation is provided in the <zowe.runtimeDirectory>/components/app-
server/share/zlux-app-server/doc/swagger/server-plugins-api.yaml file. To see it in HTML
format, you can paste the contents into the Swagger editor at https://editor.swagger.io/.
Note: The "agent" end points interact with the agent specified in the zowe configuration file. By default this
is ZSS.
Configuring Zowe CLI environment variables
Version: v2.0.x LTS

This section explains how to configure Zowe CLI using environment variables.
By default, Zowe CLI configuration is stored on your computer in the C:\Users\user01\.zowe directory.
The directory includes log files, profile information, and installed CLI plug-ins. When troubleshooting, refer to
the logs in the imperative and zowe folders.

Setting the CLI home directory

You can set the location on your computer where Zowe CLI creates the .zowe directory, which contains log
files, profiles, and plug-ins for the product:
Environment Description Values Default
Variable
Zowe CLI home Any valid path on your Your computer default
ZOWE_CLI_HOME
directory location computer home directory

Setting CLI log levels

You can set the log level to adjust the level of detail that is written to log files:
Important! Setting the log level to TRACE or ALL might result in "sensitive" data being logged. For example,
command line arguments will be logged when TRACE is set.
Environment Variable Description Values Default

Zowe CLI logging Log4JS log levels (OFF, TRACE,

ZOWE_APP_LOG_LEVEL
level DEBUG, INFO, WARN, ERROR, WARN
FATAL)
 Environment Variable Description Values Default
Imperative CLI Log4JS log levels (OFF, TRACE,
ZOWE_IMPERATIVE_LOG_LEVEL Framework DEBUG, INFO, WARN, ERROR, WARN
logging level FATAL)

Setting CLI daemon mode properties

By default, the CLI daemon mode binary creates or reuses a file in the user's home directory each time a
Zowe CLI command runs. In some cases, this behavior might be undesirable. For example, the home
directory resides on a network drive and has poor file performance. To change the location that the daemon
uses, set the environment variables that are described in the following table:
Platform Environment Variable Description Values Defaul
Lets you override the
complete path to the
directory that will hold <your_home_dir>/.z
daemon files related to Any valid Examples:
this user. The directory path on
All ZOWE_DAEMON_DIR can contain the following your Windows:
files: computer %HOMEPATH%\.zo
daemon.lock Linux: $HOME/.zo
daemon.sock

daemon_pid.json

Lets you override the last

two segments of the Any valid
Windows name of the path on
(only) ZOWE_DAEMON_PIPE communication pipe your \\.\pipe\%USERNAME
between the daemon computer
executable (.exe) and the
daemon.
Configuring the Zowe APIs
Version: v2.0.x LTS

Review the security considerations for Zowe APIs and learn how to prevent the Denial of Service (DoS)
attacks.
The default configuration before Zowe version 1.14.0 contains Data sets and Unix files and Jobs API
microservices which might be vulnerable to DoS attacks in the form of slow https attacks. You can add
additional configuration to the start script of these components in order to prevent resource starvation via
slow https attacks.
To update the configuration of the Data sets and Unix files component, modify the start.sh script
within the runtime component directory /zowe/runtime/components/files-api/bin .
To update the configuration of the Jobs component, modify the start.sh script within the runtime
component directory /zowe/runtime/components/jobs-api/bin .
Ensure that the -Dserver.connection-timeout=8000 parameter is set. This parameter specifies how
long the component waits to receive all the required information from the client that makes a request.
See a snippet of a configured start.sh script for the Jobs component as follows:
In version 1.14.0 and later, the preceding snippet reflects the default configuration.
Advanced Gateway features configuration
Version: v2.0.x LTS

As a system programmer who wants to configure advanced Gateway features of the API Mediation Layer,
you can customize Gateway parameters by modifying either of the following files:
<Zowe runtime directory>/components/gateway/bin/start-gateway.sh

<Zowe runtime directory>/components/gateway/manifest.yaml

zowe.yaml

The parameters begin with the -D prefix, similar to all the other parameters in the file.
Note: Restart Zowe to apply changes to the parameter.
Follow the procedures in the following sections to customize Gateway parameters according to your
preferences:
Prefer IP Address for API Layer services
SAF as an Authentication provider
Enable JWT token refresh endpoint
Change password with SAF provider
Gateway retry policy
Gateway client certificate authentication
Gateway timeouts
CORS handling
Encoded slashes
Connection limits
Routed instance header
Distributed load balancer cache
Replace or remove catalog with another service
API Mediation Layer as a standalone component
SAF resource checking

SAF as an Authentication provider

By default, the API Gateway uses z/OSMF as an authentication provider. It is possible to switch to SAF as the
authentication provider instead of z/OSMF. The intended usage of SAF as an authentication provider is for
systems without z/OSMF. If SAF is used and the z/OSMF is available on the system, the created tokens are
not accepted by z/OSMF. Use the following procedure to switch to SAF.
Follow these steps:
. Open the zowe.yaml configuration file.
. Find or add the property components.gateway.apiml.security.auth.provider and set the
value to saf .
. Restart Zowe&trade.
Authentication requests now utilize SAF as the authentication provider. API ML can run without z/OSMF
present on the system.

Enable JWT token refresh endpoint

Enable the /gateway/api/v1/auth/refresh endpoint to exchange a valid JWT token for a new token
with a new expiration date. Call the endpoint with a valid JWT token and trusted client certificate. In case of
z/OSMF authentication provider, enable API Mediation Layer for passticket generation and configure z/OSMF
APPLID. Configure Passtickets
Follow these steps:
. Open the file zowe.yaml .
. Configure the following properties:
components.gateway.apiml.security.allowtokenrefresh: true
Add this property to enable the refresh endpoint.
components.gateway.apiml.security.zosmf.applid
If you use z/OSMF as an authentication provider, provide a valid APPLID . The API ML generates a
passticket for the specified APPLID and subsequently uses this passticket to authenticate to
z/OSMF. The default value in the installation of z/OSMF is IZUDFLT .
. Restart Zowe.
Change password with SAF provider
Update the user password using the SAF Authentication provider. To use this functionality, add the
parameter newPassword on the login endpoint /gateway/api/v1/auth/login . The Gateway service
returns a valid JWT with the response code 204 as a result of successful password change. The user is
then authenticated and can consume APIs through the Gateway. If it is not possible to change the password
for any reason, the response code is 401 .
This feature is also available in the API Catalog.
This feature is also available in the API Catalog.
Use a POST REST call against the URL /gateway/api/v1/auth/login :
Note: It is a common practice to set the limit for changing the password in the ESM. This value is set by the
parameter MINCHANGE for PASSWORD . The password can be changed once. Subsequently, it is
necessary to wait the specified time period before changing the password again.
Example:
MINCHANGE=120

where:
120

Specifies the number of days before the password can be reset

Change password with z/OSMF provider
Update the user password using the z/OSMF Authentication provider. To use this functionality, add the
parameter newPassword on the login endpoint /gateway/api/v1/auth/login . The Gateway service
returns a valid JWT with the response code 204 as a result of successful password change. The user is
then authenticated and can consume APIs through the Gateway. If it is not possible to change the password
for any reason, the response code is 401 .
This feature is also available in the API Catalog.
Use a POST REST call against the URL /gateway/api/v1/auth/login :
Note: In order to use the password change functionality via z/OSMF, it is necessary to install the PTF for
APAR PH34912.

Gateway retry policy

To change the Gateway retry policy, edit properties in the <Zowe install
directory>/components/gateway/bin/start.sh file:

All requests are disabled as the default configuration for retry with one exception: the server retries GET
requests that finish with status code 503 . To change this default configuration, include the following
parameters:
ribbon.retryableStatusCodes
Provides a list of status codes, for which the server should retry the request.
Example: -Dribbon.retryableStatusCodes="503, 404"
ribbon.OkToRetryOnAllOperations
Specifies whether to retry all operations for this service. The default value is false . In this case, only
GET requests are retried if they return a response code that is listed in
ribbon.retryableStatusCodes . Setting this parameter to true enables retry requests for all
methods which return a response code listed in ribbon.retryableStatusCodes .
Note: Enabling retry can impact server resources due to request body buffering.
ribbon.MaxAutoRetries
Specifies the number of times a failed request is retried on the same server. This number is multiplied
with ribbon.MaxAutoRetriesNextServer . The default value is 0 .
ribbon.MaxAutoRetriesNextServer
Specifies the number of additional servers that attempt to make the request. This number excludes the
first server. The default value is 5 .

Gateway client certificate authentication

Beginning with release 1.19 LTS, it is possible to authenticate using client certificates. The feature is
functional and tested, but automated testing on various security systems is not complete. As such, the
feature is provided as a beta release for early preview. If you would like to offer feedback using client
certificate authentication, please create an issue against the api-layer repository. Client Certificate
authentication will move out of Beta once test automation is fully implemented across different security
systems.
Use the following procedure to enable the feature to use a client certificate as the method of authentication
for the API Mediation Layer Gateway.
Follow these steps:
. Open the zowe.yaml configuration file.
. Configure the following properties:
components.gateway.apiml.security.x509.enabled
This property is the global feature toggle. Set the value to true to enable client certificate
functionality.
components.gateway.apiml.security.zosmf.applid
When z/OSMF is used as an authentication provider, provide a valid APPLID to allow for client
certificate authentication. The API ML generates a passticket for the specified APPLID and
subsequently uses this passticket to authenticate to z/OSMF. The default value in the installation of
z/OSMF is IZUDFLT .
Note: The following steps are only required if the ZSS hostname or default Zowe user name are
altered:
. Change the following property if user mapping is provided by an external API:
components.gateway.apiml.security.x509.externalMapperUrl
Note: Skip this step if user mapping is not provided by an external API.
The API Mediation Gateway uses an external API to map a certificate to the owner in SAF. This property
informs the Gateway about the location of this API. ZSS is the default API provider in Zowe. You can
provide your own API to perform the mapping. In this case, it is necessary to customize this value.
 The following URL is the default value for Zowe and ZSS:
. Add the following property if the Zowe runtime userId is altered from the default ZWESVUSR :
components.gateway.apiml.security.x509.externalMapperUser
Note: Skip this step if the Zowe runtime userId is not altered from the default ZWESVUSR .
To authenticate to the mapping API, a JWT is sent with the request. The token represents the user that
is configured with this property. The user authorization is required to use the IRR.RUSERMAP resource
within the FACILITY class. The default value is ZWESVUSR . Permissions are set up during
installation with the ZWESECUR JCL or workflow.
If you customized the ZWESECUR JCL or workflow (the customization of zowe runtime user: // SET
ZOWEUSER=ZWESVUSR * userid for Zowe started task ) and changed the default USERID,
create the components.gateway.apiml.security.x509.externalMapperUser property and
set the value by adding a new line as in the following example:
Example:
. Restart Zowe&trade .

Gateway timeouts
Use the following procedure to change the global timeout value for the API Mediation Layer instance.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property components.gateway.apiml.gateway.timeoutmillis , and set the
value to the desired value.
. Restart Zowe&trade .
If you require finer control, you can edit the <Zowe install
directory>/components/gateway/bin/start.sh , and modify the following properties:

apiml.gateway.timeoutMillis
This property defines the global value for http/ws client timeout.
Add the following properties to the file for the API Gateway:
Note: Ribbon configures the client that connects to the routed services.
ribbon.connectTimeout
Specifies the value in milliseconds which corresponds to the period in which API ML should establish a
single, non-managed connection with the service. If omitted, the default value specified in the API ML
Gateway service configuration is used.
ribbon.readTimeout
Specifies the time in milliseconds of inactivity between two packets in response from this service to API
ML. If omitted, the default value specified in the API ML Gateway service configuration is used.
ribbon.connectionManagerTimeout
The HttpClient employs a special entity to manage access to HTTP connections called by the HTTP
connection manager. The purpose of an HTTP connection manager is to serve as a factory for new
HTTP connections, to manage the life cycle of persistent connections, and to synchronize access to
persistent connections. Internally, the connections that are managed serve as proxies for real
connections. ConnectionManagerTimeout specifies a period during which managed connections
with API ML should be established. The value is in milliseconds. If omitted, the default value specified in
the API ML Gateway service configuration is used.

CORS handling
You can enable the Gateway to terminate CORS requests for itself and also for routed services. By default,
Cross-Origin Resource Sharing (CORS) handling is disabled for Gateway routes gateway/api/v1/** and
for individual services. After enabling the feature as stated in the prodecure below, API Gateway endpoints
start handling CORS requests and individual services can control whether they want the Gateway to handle
CORS for them through the Custom Metadata parameters.
When the Gateway handles CORS on behalf of the service, it sanitizes defined headers from the
communication (upstream and downstream). Access-Control-Request-Method,Access-Control-
Request-Headers,Access-Control-Allow-Origin,Access-Control-Allow-Methods,Access-
Control-Allow-Headers,Access-Control-Allow-Credentials,Origin The resulting request to
the service is not a CORS request and the service does not need to do anything extra. The list can be
overridden by specifying different comma-separated list in the property
components.gateway.apiml.service.ignoredHeadersWhenCorsEnabled in zowe.yaml
Additionally, the Gateway handles the preflight requests on behalf of the service when CORS is enabled in
Custom Metadata, replying with CORS headers:
Access-Control-Allow-Methods: GET,HEAD,POST,DELETE,PUT,OPTIONS

Access-Control-Allow-Headers: origin, x-requested-with

Access-Control-Allow-Credentials: true

Access-Control-Allow-Origin: *

Alternatively, list the origins as configured by the service, associated with the value
customMetadata.apiml.corsAllowedOrigins in Custom Metadata.
If CORS is enabled for Gateway routes but not in Custom Metadata, the Gateway does not set any of the
previously listed CORS headers. As such, the Gateway rejects any CORS requests with an origin header for
the Gateway routes.
Use the following procedure to enable CORS handling.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property components.gateway.apiml.service.corsEnabled and set the value
to true .
. Restart Zowe&trade .
Requests through the Gateway now contain a CORS header.

Encoded slashes
By default, the API Mediation Layer accepts encoded slashes in the URL path of the request. If you are
onboarding applications which expose endpoints that expect encoded slashes, it is necessary to keep the
default configuration. We recommend that you change the property to false if you do not expect the
applications to use the encoded slashes.
Use the following procedure to reject encoded slashes.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property components.gateway.apiml.service.allowEncodedSlashes and set
the value to false .
. Restart Zowe&trade .
Requests with encoded slashes are now rejected by the API Mediation Layer.

Connection limits
By default, the API Gateway accepts up to 100 concurrent connections per route, and 1000 total concurrent
connections. Any further concurrent requests are queued until the completion of an existing request. The
API Gateway is built on top of Apache HTTP components that require these two connection limits for
concurrent requests. For more information, see Apache documentation.
Use the following procedure to change the number of concurrent connections.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property components.gateway.server.maxConnectionsPerRoute and set the
value to an appropriate positive integer.
. Find or add the property components.gateway.server.maxTotalConnections and set the value
to an appropriate positive integer.

Routed instance header

The API Gateway can output a special header that contains the value of the instance ID of the API service
that the request has been routed to. This is useful for understanding which service instance is being called.
The header name is X-InstanceId , and the sample value is discoverable-
client:discoverableclient:10012 . This is identical to instanceId property in the registration of
the Discovery service.
Use the following procedure to output a special header that contains the value of the instance ID of the API
service.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property with value
components.gateway.apiml.routing.instanceIdHeader:true .
. Restart Zowe.

Distributed load balancer cache

You can choose to distribute the load balancer cache between instances of the API Gateway. To distribute
the load balancer cache, it is necessary that the caching service is running. Gateway service instances are
reuqired to have the same DN (Distinguished name) on the server certificate.
Use the following procedure to distribute the load balancer cache between instances of the API Gateway.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property with value components.gateway.apiml.loadBalancer.distribute:
true .

. Restart Zowe.

Replace or remove the Catalog with another service

By default, the API Mediation Layer contains API Catalog as a service showing available services. As the API
Mediation Layer can be successfully run without this component it is possible to replace or remove the
service from the Gateway home page and health checks. The following section describes the behavior of the
Gateway home page and health checks.
The default option displays the API Catalog.
A value can also be applied to components.gateway.apiml.catalog.serviceId .
Examples:
none
 Nothing is displayed on the Gateway home page and the Catalog is removed from
/application/health

alternative-catalog

An alternative to the API Catalog is displayed

metrics-dashboard

A possible dashboard that could appear in place of the API Catalog

Notes:
If the application contains the homePageUrl and statusPageRelativeUrl , then the full set of
information is displayed.
If the application contains the homePageUrl the link is displayed without the UP information.
If the application contains the statusPageRelativeUrl then UP or DOWN is displayed based on
the statusPage without the link.
Use the following procedure to change or replace the Catalog service.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property components.gateway.apiml.catalog.serviceId . Set the value with
the following options:
Set the value to none to remove the Catalog service.
Set the value to the ID of the service that is onboarded to the API Mediation Layer.

API Mediation Layer as a standalone component

You can start the API Mediation Layer independently of other Zowe components. By default, the Gateway,
Zowe System Services, and Virtual Desktop start when Zowe runs. To limit consumed resources when the
Virtual Desktop or Zowe System Services are not required, it is possible to specify which components start
in the context of Zowe. No change is required during the installation process to support this setup.
Once Zowe is installed, use the following procedure to limit which components start.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property components.*.enabled and set this property to false for all
components that should not be started.
. Restart Zowe&trade .
To learn more about the related section of the environment file, see Creating and configuring the Zowe
instance directory. We recommend you open this page in a new tab.

SAF Resource Checking

The API ML can check for the authorization of the user on certain endpoints. Access to a SAF resource is
checked with ESM.
Verification of the SAF resource is provided by the following three providers:
endpoint

This is the highest priority provider, such as a REST endpoint call (ZSS or similar one). This option is
disabled by default. In Zowe, ZSS has the API to check for SAF resource authorization.
native

The Native JZOS classes from Java are used to determine SAF resource access. This is the default
provider.
dummy

This is the lowest priority provider. This is the dummy implementation and is defined in a file.
Note: Verification of the SAF resource uses the first available provider based on the specified priority. The
default configuration resolves to the native provider.
You can select a specific provider by specifying the
components.gateway.apiml.security.authorization.provider key in the zowe.yaml file.
Use the parameter value to strictly define a provider. If verification is disabled, select the endpoint option.
Follow these steps:
 . Open the file zowe.yaml .
. Find or add the property components.gateway.apiml.security.authorization.provider
and set desired value.
. Restart Zowe&trade .
Examples:
Note: To configure the endpoint provider, add the following additional property:
components.gateway.apiml.security.authorization.endpoint.enabled: true

To use the endpoint provider, customize the URL corresponding to the SAF resource authorization. By
default, the ZSS API is configured and used.
Follow these steps:
. Open the file zowe.yaml .
. Find or add the property
components.gateway.apiml.security.authorization.endpoint.url and set desired value.
The default value for ZSS API is
https://${ZWE_haInstance_hostname}:${GATEWAY_PORT}/zss/api/v1/saf-auth

. Restart Zowe&trade .
Checking providers
REST endpoint call
The REST provider calls the external API to retrieve information about access rights. To enable the feature
outside of the mainframe, such as when running in Docker, you can use a REST endpoint call using the GET
method:
Method: GET
URL: {base path}/{userId}/{class}/{entity}/{level}
Response:
Note: For more information about this REST endpoint call, see ZSS implementation.
Native
The Native provider is the easiest approach to use the SAF resource checking feature on the mainframe.
Enable this provider when classes com.ibm.os390.security.PlatformAccessControl and
com.ibm.os390.security.PlatformReturned are available on the classpath. This approach uses the
following method described in the IBM documentation: method.
Note: Ensure that the version of Java on your system has the same version of classes and method
signatures.
Dummy implementation
The Dummy provider is for testing purpose outside of the mainframe.
Create the file saf.yml and locate it in the folder, where is application running or create file mock-
saf.yml in the test module (root folder). The highest priority is to read the file outside of the JAR. A file
(inner or outside) has to exist.
The following YAML presents the structure of the file:
Notes:
Classes and resources are mapped into a map, user IDs into a list.
The load method does not support formatting with dots, such as shown in the following example:
Example: {CLASS}.{RESOURCE} Ensure that each element is separated.
The field safAccess is not required to define an empty file without a definition.
Classes and resources cannot be defined without the user ID list.
When a user has multiple definitions of the same class and resource, only the most privileged access
level loads.
Discovery Service configuration parameters
Version: v2.0.x LTS

Zowe runtime configuration parameters

As an application developer who wants to run Zowe, set the following parameters during the Zowe runtime
configuration by modifying the <Zowe install
directory>/components/discovery/bin/start.sh file:

API ML configuration
Eureka configuration

API ML configuration
apiml.discovery.userid
The Discovery service in HTTP mode protects it's endpoints with basic authentication instead of client
certificate. This parameter specifies the userid. The default value is eureka .
apiml.discovery.password
This parameter specifies the password for the basic authentication used by the Discovery Service in
HTTP mode. The default value is password .
apiml.discovery.allPeersUrls
This parameter contains the list of URLs of the Discovery Service in case of multiple instances of the
service on different host. Example:
Note: Each URL within the list must be separated by a comma.
apiml.discovery.staticApiDefinitionsDirectories
The static definition directories can be specified as a parameter at startup and will be scanned by the
Discovery Service. These directories contains the definitions of static services. Example:
apiml.discovery.serviceIdPrefixReplacer
 This parameter is used to modify the service ID of a service instance, before it registers to API ML.
Using this parameter ensures compatibility of services that use a non-conformant organization prefix
with v2, based on Zowe v2 conformance. The value of the
*apiml.discovery.serviceIdPrefixReplacer parameter is represented as a tuple that
contains two strings, separated by a comma. The format of this parameter contains the following two
elements:
First, the prefix that you want to replace in the service ID
Second, the new prefix that will be replaced
Example: The value of the parameter has the following format:
oldServiceIdPrefix,newServiceIdPrefix

Set this parameter in your Zowe YAML configuration (typically zowe.yaml ) by defining
configs.apiml.discovery.serviceIdPrefixReplacer . For example, defining it globally:

Or defining it only for lpar1 high availability instance:

Eureka configuration
The Discovery Service contains a configuration for implementing the client-side service discovery and for
defining a Eureka Server for service registry. Such configuration is shown below:
eureka.client.registerWithEureka If we make this property as true then while the server starts the
inbuilt client will try to register itself with the Eureka server.
eureka.client.registerWithEureka The inbuilt client will try to fetch the Eureka registry if we configure
this property as true.
eureka.client.serviceUrl.defaultZone A fallback value that provides the Eureka service URL for any
client that does not express a preference (in other words, it is a useful default).
More information about the other Eureka parameters can be found in the Spring Cloud Netflix Eureka
documentation.
API Gateway configuration parameters
Version: v2.0.x LTS

As an application developer who wants to change the default configuration of the API Mediation Layer, set
the following parameters by modifying the <Zowe install
directory>/components/gateway/bin/start.sh file:

Runtime configuration
Environment variables
Service configuration
Zuul configuration
Hystrix configuration
AT-TLS

Runtime configuration
This section describes runtime configuration properties.
apiml.service.hostname
This property is used to set the API Gateway hostname.
apiml.service.port
This property is used to set the API Gateway port.
apiml.service.discoveryServiceUrls
This property specifies the Discovery Service URL used by the service to register to Eureka.
apiml.service.preferIpAddress
Set the value of this property to true to advertize a service IP address instead of its hostname.
Notes:
If you set this property to true on the Discovery Service, ensure that you modify the value of
discoveryLocations: to use the IP address instead of the hostname. Failure to modify the
 discoveryLocations: value prevents Eureka from detecting registered services. As a result,
the available-replicas is empty.
Enabling this property may also cause issues with SSL certificates and Subject Alternative Name
(SAN).
apiml.cache.storage.location
This property specifies the location of the EhCache used by Spring.
Note: It is necessary for the API ML process to have write access to the cache location.
apiml.security.ssl.verifySslCertificatesOfServices
This parameter makes it possible to prevent server certificate validation.
Important! Ensure that this parameter is set to true in production environments. Setting this
parameter to false in production environments significantly degrades the overall security of the
system.
apiml.security.auth.zosmfServiceId
This parameter specifies the z/OSMF service id used as authentication provider. The service id is
defined in the static definition of z/OSMF. The default value is zosmf .
apiml.zoweManifest
This parameter lets you view the Zowe version by using the /version endpoint. To view the version
requires setting up the launch parameter of the API Gateway - apiml.zoweManifest with a path to
the Zowe build manifest.json file. This file is usually located in the root folder of Zowe build. If the
encoding of manifest.json file is different from UTF-8 and IBM1047, ensure that you set up the
launch parameter of API Gateway - apiml.zoweManifestEncoding with correct encoding.
Note: It is also possible to know the version of API ML and Zowe (if API ML used as part of Zowe), using
the /gateway/api/v1/version endpoint in the API Gateway service in the following format:
apiml.security.auth.tokenProperties.expirationInSeconds
This property is relevant only when the JWT is generated by the API Mediation Layer. API ML generation
of the JWT occurs in the following cases:
 z/OSMF is only available as an older version which does not support JWT tokens
The SAF provider is used
To use a custom configuration for z/OSMF which changes the expiration of the LTPA token, it is
necessary to also set the expiration in this parameter.
Note: The default value is 8 hours which mimicks the 8 hour default expiration of the LTPA token in
z/OSMF.
Follow these steps:
i. Open the file <Zowe install directory>/components/gateway/bin/start.sh .
ii. Find the line that contains -cp ${ROOT_DIR}"/components/gateway/gateway-
service.jar":/usr/include/java_classes/IRRRacf.jar .

iii. Before this line, add a new line in the following format:
where:
{expirationTimeInSeconds}

refers to the specific time before expiration

iv. Restart Zowe&trade.
ibm.serversocket.recover
In a multiple network stack environment (CINET), when one of the stacks fails, no notification or Java™
exception occurs for a Java program that is listening on an INADDR_ANY socket. When new stacks
become available, the Java application does not become aware of these stacks until the application
rebinds the INADDR socket. By default, this parameter is enabled in the API Gateway. As a result, the
NetworkRecycledException exception is thrown to the application to allow it to either fail or
attempt to rebind. For more information, see the IBM documentation.
java.io.tmpdir
This property is a standard Java system property which is used by the disk-based storage policies. This
property determines where the JVM writes temporary files, including those written by these storage
policies. The default value is typically /tmp on Unix-like platforms.
 spring.profiles.include
This property can be used to unconditionally add active profiles. For more information, see the Spring
documentation.
server.maxTotalConnections and server.maxConnectionsPerRoute
These two properties are used to set the number of concurrent connections. Further connection
requests that put the number of connections over either of these limits are queued until an existing
connection completes. The API Gateway is built on top of Apache HTTP components that require these
two connection limits for concurrent requests. For more information, see Apache documentation.
Environment variables
You can add additional environment variables to store configuration properties for the API Mediation Layer.
Note: Use either dot separation, or the UPPER_CASE naming convention when adding an additional
environmental variable.
One use case for adding an environmental variable is to change the authentication provider. The SAF
Authentication Provider allows the API Gateway to authenticate directly with the z/OS SAF provider
that is installed on the system. The user needs a SAF account to authenticate. Use this procedure to
customize authentication provider.
Follow the steps:
. Open the file <Zowe instance directory>/instance.env .
. Add a new line with the following property:
apiml.security.auth.provider=saf .

Service configuration
For information about service configuration parameters, see Onboarding a REST API service with the Plain
Java Enabler (PJE).

Zuul configuration
As a provider for routing and filtering, the API Gateway contains a Zuul configuration as shown in the
following example.
Example:
The Zuul configuration allows the API Gateway to act as a reverse proxy server through which API requests
can be routed from clients on the northbound edge to z/OS servers on the southbound edge.
Note: For more information about Zuul configuration parameters, see the Spring Cloud Netflix
documentation.

Hystrix configuration
The API Gateway contains a Hystrix configuration as shown in the following example.
Example:
Hystrix is a latency and fault tolerance library designed to isolate points of access to remote systems,
services and third-party libraries, stop cascading failure, and enable resilience in complex distributed
systems where failure is inevitable.
Note: For more information about Hystrix configuration parameters, see the Netflix - Hystrix documentation.

AT-TLS
The communication server on z/OS provides a functionality to encrypt HTTP communication for on-platform
running jobs. This functionality is refered to as Application Transparent Transport Layer Security (AT-TLS).
Starting with Zowe version 1.24, it is possible to leverage AT-TLS within the API Mediation Layer. Each API
ML component can run with AT-TLS rules applied. Some components, such as the Discovery service, can be
made AT-TLS aware by enabling the AT-TLS profile, whereby TLS information can be utilized. Such
information could be a client certificate. To enable the AT-TLS profile and disable the TLS application in API
ML, update zowe.yaml with following values under the respective component in the components
section:
While API ML can not handle TLS on its own, the Mediation Layer needs information about the server
certificate that is defined in the AT-TLS rule. Update the zowe.yaml file for each respective APIML
component in the components sections with the path to the SAF Key ring from the AT-TLS rule and
specify the alias that is used for Inbound communication:
Note: This procedure does not configure AT-TLS on z/OS, but rather enables API ML to work with AT-TLS in
place.
Extending Zowe
Version: v2.0.x LTS

Zowe is designed as an extensible tools platform. One of the Zowe architecture goals is to provide
consistent interoperability between all Zowe components including extensions. The Zowe Conformance
Program defines the criteria to help accomplish the aforementioned goal. By satisfying the Zowe
Conformance Program criteria, extension providers are assured that their software remains functional
throughout the Zowe release cycle. For more information, see the Zowe Conformance Program.
Zowe can be extended in the following ways:
Extend Zowe CLI
Extend Zowe API Mediation Layer
Dynamic API registration
Static API registration
Add a plug-in to the Zowe Desktop
Extend Zowe Explorer
To help Zowe extenders better understand how extensions are developed and deployed, we provide a set of
sample extensions. These sample extensions contain the necessary boilerplate project setup, application
code, and installation scripts to jumpstart the extension development and deployment to Zowe.
Note: For more information on the architecture of Zowe, see Zowe Architecture.

Extend Zowe CLI

Zowe CLI extenders can build plug-ins that provide new commands. Zowe CLI is built using Node.js and is
typically run on a machine other than z/OS, such as a PC, where the CLI can be driven through a terminal or
command prompt, or on an automation machine such as a DevOps pipeline orchestrator.
For more information about extending the Zowe CLI, see Developing a new plug-in. This article includes a
sample plug-in that is provided with the tutorial; see Installing the sample plug-in.

Extend Zowe API Mediation Layer

Zowe API Mediation Layer extenders can build and onboard additional API services to the API ML
microservices ecosystem. REST APIs can register with the API Mediation Layer, which makes them available
in the API Catalog and for routing through the API Gateway.
To register a z/OS service with the API Mediation Layer, there are two approaches:
Dynamic API registration
Static API registration
For information about how to onboard REST APIs, see the Onboarding Overview.
To streamline the process of onboarding new REST API services to the API Mediation Layer, see Onboarding
a REST API service with the YAML Wizard
Dynamic API registration
Registration of a REST API service to the API ML is performed through a call to the Discovery Service by
sending registration data and metadata for the service being registered. Registration requires that the z/OS
service must know the web address of the API ML Discovery Service. When Dynamic registration is
performed, the service that performs the registration must periodically send heartbeat requests to the
Discovery Service for each registered service instance. These heartbeat requests serve to renew the
corresponding service instance registration with API ML. These requests enable the Discovery Service to
monitor the availability of registered service instances. Services that are registered dynamically display the
status of the service in the API Catalog after initial service registration.
For more information about how to build a service which is able to register, see the Onboarding Overview.
Static API registration
For services that cannot be modified to be dynamically discoverable, it is possible onboard them to the API
ML by providing the API ML a static definition file with API service details. This registration method does not
require modifications to the existing API service code. For more information, see Onboard a REST API
without code changes required. Unlike services that use Dynamic API registration, the status of services
onboarded through Static API registration is not displayed in the API Catalog.

Add a plug-in to the Zowe Desktop

The Zowe Desktop allows a user to interact with z/OS applications through a web browser. The Desktop is
served by the Zowe Application Framework Server on z/OS, also known as Z Lightweight User Experience
(ZLUX). The Zowe desktop comes with a set of default applications. You can extend it to add new
applications. For more information, see Developing for Zowe Application Framework.
The Zowe Desktop is an angular application that allows native plug-ins to be built that provide for a high level
of interoperability with other desktop components. The React JavaScript toolkit is also supported.
Additionally, you can include an existing web application in the Zowe Desktop using an iframe.
Notes: For more information, see the following samples:
Sample iframe App.
Sample Angular App.
Sample React App.

Extend Zowe Explorer

Zowe Explorer provides extension APIs that assist third party extenders to create extensions that access
Zowe Explorer resource entities to enrich the user experience. There are many ways Zowe Explorer can be
extended to support many different use cases.
For the kinds of extensions that are supported and how to get started with extending Zowe Explorer, see
Extensions for Zowe Explorer.

Sample extensions
Sample Zowe API and API Catalog extension
The repository https://github.com/zowe/sample-node-api contains a sample Zowe extension with a node
server providing sample APIs for looking at cars in a dealership. For more information, see sample-node-api.
Sample Zowe Desktop extension
The repository https://github.com/zowe/sample-trial-app contains a sample Zowe extension with a node
server providing a web page that gives a user interface to the APIs included with the API sample above.
Packaging z/OS extensions
Version: v2.0.x LTS

You can extend Zowe in multiple ways. You may extend Zowe with microservices, which may start a new
service within Zowe. You can also create Zowe App Framework plug-ins to provide users with a UI.
Before you start, review the following terms:
component:
Component refers to the most generic way to describe a program which can work within Zowe. It can be
a microservice, a Zowe App Framework plug-in, or even just a shared program to be used by other
Zowe components. This is also the generic word when referring to both Zowe core components and
extensions. In most of the cases described in this topic, this terminology does not include programs
running on the client side, like Zowe CLI plug-in or Zowe Explorer (VSCode extension).
extension
Extension is similar to component but excludes Zowe core components. It is recommended that you
install all Zowe extensions into a shared extension directory.

Zowe server component package format

You can package Zowe components (extensions) into various formats. You can package them as a stand-
alone PAX, ZIP, or TAR file. You can also bundle and ship your Zowe extension(s) within another product.
A typical component package, for example, jobs-api-package-1.0.4.zip , consists of the following
files and directories:
manifest.yaml

Refers to the Zowe component manifest file. You can find detailed definition of manifest in Server
Component Manifest File Reference.
schema.json

An example filename of the json schema file specified by the manifest property schemas.configs as
detailed in Server Component Manifest File Reference. The file details the parameters that are valid for
 the component's configuration within Zowe server configuration files. See documentation on server
component schema files for more information.
apiml-static-registration.yaml.template

Refers to a supporting file that instructs the Zowe launch script how to register this extension service to
the API Mediation Layer Discovery service. In this case, this file is referred in the manifest.yaml
apimlServices.static[0].file field. This file is optional depending on the function of the
component and you can change and customize the file name in the manifest file.
bin/(configure|start|validate).sh

This file contains the Zowe component lifecycle scripts. You may not need these files depending on the
function of the component. You can find detailed definition of lifecycle scripts in Zowe component
runtime lifecycle.
It is also suggested that you put the following files into the package:
README.md

This file is a brief introduction to your extension in Markdown format, including how it should be
installed, configured, verified, and so on.
LICENSE

This is the full license text file.

If you decide to bundle and ship Zowe extensions within another product, you can put the whole directory
structure presented previously into your product package as subdirectories. Take the following structure as
an example.

Zowe component manifest

Zowe extensions, as well as core components, can use a manifest file to describe itself. Check Server
Component Manifest File Reference for details.

Sample manifests
For examples of manifests thoughout Zowe GitHub repositories, see the following links:
API Catalog manifest.yaml
Jobs API manifest.yaml
Sample Node API and API Catalog extension manifest.yaml
Sample Zowe App Framework extension manifest.yaml
Install Zowe server component
Version: v2.0.x LTS

Learn how to install Zowe server components or extensions by using zwe components install
commands or manually.

Install component
Zowe ships zwe components install command to help end-user to install any Zowe server
components (extensions). Zowe core components are also installed with this command. In order to be
compatible with the command, components must follow Zowe server component package format standard.
Important this command will also enable the component globally by updating your zowe.yaml
configuration file. You can pass --skip-enable to disable this behavior.
Execute the command from z/OS USS. Use the following command line parameters:
--component-file|--component|-o

(String, Required) Defines the path to the component package or directory.

--config|-c

(String, Required) Defines the path to the Zowe YAML configuration. zwe components install
relies on the zowe.extensionDirectory definition to know where the component will be installed.
-- --skip-enable
(Boolean, Optional) Tells the command do not enable the component by updating zowe.yaml
configuration file.
--auto-encoding|-e

(String, Optional) Defines whether to automatically tag the encoding of the files that are shipped with
the component. The default value is auto , which indicates that the script determines whether the
automatic tagging is needed or not.
 Note: The automatic tagging process is opinionated about which file extensions should be in which
encoding. If this does not fit in your needs, a pax format is recommended to include the tagging
information into your package. This option is only applicable for z/OS. The following list presents the
allowed values:
yes

This option automatically tag the encoding of the files.

no

Do not automatically tag encoding of the files.

auto

Tag only when manifest is in ISO8859-1 encoding.

--log-dir|--log|-l

(String, Optional) Specifies the path to the log directory.

--debug|--verbose|-v

(Boolean, Optional) Enable debug level logging. This will help on troubleshooting issues.
--trace|-vv

(Boolean, Optional) Enable the most detail trace level logging. This will help on troubleshooting issues.
Examples:
The following command installs the my-zowe-component-1.2.3.pax into
/global/zowe/extensions which is defined as zowe.extensionDirectory in
/path/to/my/zowe.yaml .

Enable and disable component

Zowe ships zwe components enable and zwe components disable commands to help you enable
and disable Zowe server component (extension). In order to be compatible with these commands,
components must follow Zowe server component package format standard.
Important these commands will update your zowe.yaml configuration file.
Note zwe components install command will enable the component globally if --skip-enable is
not passed.
Execute these commands from z/OS USS. Use the following command line parameters:
--component|-o

(String, Required) Defines the component name should be enabled or disabled.

--config|-c

(String, Required) Defines the path to the Zowe YAML configuration. zwe components install
relies on the zowe.extensionDirectory definition to know where the component will be installed.
--ha-instance|-i

(String, Optional) Defines the Zowe high availability instance ID of where the component will be enabled
or disabled. If this argument is not passed, the component will be enabled/disabled globally from
components.<component>.enabled . If this argument has a value, only specified HA instance will
be changed, which is haInstances.<ha-instance>.components.<component>.enabled .
--log-dir|--log|-l

(String, Optional) Specifies the path to the log directory.

--debug|--verbose|-v

(Boolean, Optional) Enable debug level logging. This will help on troubleshooting issues.
--trace|-vv

(Boolean, Optional) Enable the most detail trace level logging. This will help on troubleshooting issues.
Examples:
The following command enables my-zowe-component .
The following command will disable my-zowe-component on HA instance lpar1 . The configuration
logs write to /var/zowe/logs .
Install and configure manually
Zowe core components
The Zowe runtime directory delivers its core components in the <RUNTIME_DIR>/components/
directory. A typical components directory looks like this:
Same as all Zowe server components, Zowe core components can be enabled or disabled by setting
components.<component>.enabled to true or false .

Zowe z/OS extensions

All Zowe z/OS extension runtime programs are installed into a single location which is defined as
zowe.extensionDirectory in zowe.yaml . Each extension should be represented with the extension
name in this directory, and use either a directory or a symbolic link.
The Zowe launch script reads components.<component>.enabled and haInstances.<ha-
instance>.components.<component>.enabled defined in zowe.yaml to determine whether to start
an extension in current HA instance. The value of this enabled is boolean either true or false .
Example:
The vendor MYVENDOR has a product named MYAPP that installs into /usr/lpp/myvendor/myapp .
There is one Zowe extension shipped within the product in the directory
/usr/lpp/myvendor/myapp/zowe-ext . This subdirectory is a Zowe extension so that the product can
be started and stopped with Zowe and run as an address space under the ZWESLSTC started task in the
Zowe USS shell.
The directory /usr/lpp/myvendor/myapp/zowe-ext should include a manifest.yaml file to
describe the extension. The script /usr/lpp/myvendor/myapp/zowe-ext/bin/validate.sh checks
that the environment is configured correctly and the script /usr/lpp/myvendor/myapp/zowe-
ext/bin/start.sh starts the vendor application. The /usr/lpp/myvendor/myapp/zowe-
ext/manifest.yaml should look like this:

Because MYAPP is shipped within another product, the installation should create a symbolic link in
zowe.extensionDirectory directory.

Also, myapp is enabled in zowe.yaml like this.

When the Zowe instance is launched by running zwe start command, it will read manifest commands
instructions and call the /usr/lpp/myvendor/myapp/zowe-ext/bin/start.sh script. The started
task will create an address space under ZWESLSTC for the vendor component. When the Zowe instance is
stopped, the address space is terminated.
Zowe server component runtime lifecycle
Version: v2.0.x LTS

Zowe runtime lifecycle

This topic describes the runtime lifecycle of Zowe core components and how an offering that provides a
Zowe extension can set up runtime lifecycle for their component.
The Zowe UNIX System Services (USS) components are run as part of the started task ZWESLSTC . For
more information, see Starting Zowe from a USS shell. There are two key USS directories that play different
roles when launching Zowe.
The Zowe runtime directory <RUNTIME_DIR> that contains the executable files is an immutable set of
directories and files that are replaced each time a new release is applied. The initial release or an
upgrade is installed either with UNIX shell scripts (see Installing Zowe runtime from a convenience
build), or SMP/E where the runtime directory is laid down initially as FMID AZWE002 and then upgraded
through rollup PTF builds (see Installing Zowe SMP/E). The Zowe runtime directory is not altered during
operation of Zowe, so no data is written to it and no customization is performed on its contents.
Important, any customizations to the original Zowe runtime directory are not recommended. This may
include installing extensions to this directory, putting your zowe.yaml or Zowe workspace into this
directory, or changing any of the files in it, etc.
The Zowe workspace directory <WORKSPACE_DIR> contains information that is specific to a launch of
Zowe. It contains temporary configuration settings that helps an instance of the Zowe server to be
started, such as ports that are used or paths to dependent Java and Node.js runtimes. Zowe runtime
user should have write permission to this directory. More than one Zowe workspace directories can be
created to allow multiple launches of a Zowe runtime, each one isolated from each other and starting
Zowe depending on how Zowe YAML configuration is configured.
The Zowe logs directory <LOGS_DIR> contains USS file logs when running Zowe. Some components
like app-server and zss will always write USS log files. Some components like APIML Gateway will write
log files to this directory if you enabled debug mode. Zowe runtime user should have write permission
to this directory.
To start Zowe, the command zwe start is run from a USS shell. This uses a program ZWELNCH to
launch the started task ZWESLSTC , passing an optional HAINST parameter to define which Zowe HA
instance will be started. It is the equivalent of using the TSO command /S
ZWESLSTC,HAINST='<HA_INSTANCE>',JOBNAME='<JOBNAME>' . The ZWELNCH program understands
your Zowe YAML configuration and will start components enabled in the <HA_INSTANCE> by executing
zwe internal start component command. If you execute zwe internal start directly, the USS
processes will not run as a started task and will run under the user ID of whoever ran the zwe internal
start command rather than the Zowe user ID of ZWESVUSR , likely leading to permission errors accessing
the contents of the <RUNTIME_DIR> as well as the Zowe certificate. For these reasons, the zwe start
script launches Zowe's USS process beneath the started task ZWESLSTC .
Zowe relies on zowe.yaml configuration file to know your customization for the instance. For more
information, see Zowe YAML Configuration File Reference.
Note:
The scripts of core Zowe components and some extensions use the helper library
<RUNTIME_DIR>/bin/libs . You can also use those functions but please keep away from functions
marked as internal or experimental .

Zowe component runtime lifecycle

Each Zowe component will be installed with its own USS directory, which contains its executable files. Within
each component's USS directory, a manifest file is required to describe itself and a bin directory is
recommended to contain scripts that are used for the lifecycle of the component. When Zowe is started, by
reading components manifest commands definition, it identifies the components that are configured to
launch and then execute the scripts of those components in the cycle of validate, configure, and start. All
components are validated, then all are configured, and finally all are started. This technique is used as
follows:
Used for the base Zowe components that are included with the core Zowe runtime.
Applies to extensions to allow vendor offerings to be able to have the lifecycle of their 'microservices'
within the Zowe USS shell and be included as address spaces under the ZWESLSTC started task.
Note:
All lifecycle scripts are executed from the root directory of the component. This directory is usually where
the component manifest is located.
Check Server Component Manifest File Reference to learn how to define lifecycle commands in component
manifest file.
Validate
Each component can optionally instruct Zowe runtime to validate itself with a USS command defined in
manifest commands.validate .
If present, the validate script performs tasks such as:
Check that the shell has the correct prerequisites.
Validate that ports are available.
Perform other steps to ensure that the component is able to be launched successfully.
During execution of the validate script, if an error is detected, then a component should echo a
message that contains information to assist a user diagnosing the problem.
Configure
Each component can optionally instruct Zowe runtime to configure itself with a USS command defined in
manifest commands.configure .
If the component has manifest defined, some configure actions will be performed automatically based on
manifest definition:
apimlServices.static : Zowe runtime will automatically parse and add your static definition to API
Mediation Layer.
appfwPlugins.[].path : Zowe runtime will automatically parse and install/configure the component
to Zowe App Framework.
It's possible to export configuration variables from the configure step to the start step. Each
component runs in separated shell space, which means that the variable of one component does not affect
the same variable of another component. For example, when you run export MY_VAR=val in
/bin/configure.sh , then the variable ${MY_VAR} will be available in your /bin/start.sh script.
However, ${MY_VAR} will not be available in other components.
Start
Each component can optionally instruct Zowe runtime to start itself with a USS command defined in
manifest commands.start . If this is not defined, for backward compatible purpose, a call to its
/bin/start.sh script will be executed if it exists. If your component is not supposed to be started by
itself, for example, the component is a shared library, you can skip this instruction.
It is up to each component to start itself based on how it has been written. We recommend that any variables
that someone who configure Zowe may need to vary, such as timeout values, port numbers, or similar, are
specified as variables in the instance.env file and then referenced as shell variables in the start.sh
script to be passed into the component runtime.
Creating and adding Zowe extension
Version: v2.0.x LTS

containers
Zowe extensions such as services and plug-ins that use Zowe component packaging can be used within a
Zowe container environment. To do this, you must deliver the extension as a container image that is
compatible with Zowe containers. You can follow Zowe's container conformance criteria to understand and
achieve compatibility.
Note: Missing z/OS dependencies must be checked before creating and adding Zowe extension containers.
You can add extension containers to a Zowe container environment the same way as Zowe's core
components by completing the following steps.
. Build and publish an extension image to a registry. For details, see Build and publish an extension image
to a registry.
. Define a deployment or job object. For details, see Define Deployment or Job object.
. Start the extension from the deployment or job definition. For details, see Start your component.

1. Build and publish an extension image to a registry

An extension must have a container image to run in a Zowe container environment. To create such images,
you can use a Dockerfile and refer to the following examples of building images for Zowe core components.
Examples:
The core components define component Dockerfiles and use GitHub Actions to build images. For example,
jobs-api is a component which has built-in web service. To build the images, this component
defines a Dockerfile at https://github.com/zowe/jobs/blob/v2.x/master/container/Dockerfile and defines
a GitHub Actions workflow at https://github.com/zowe/jobs/blob/v2.x/master/.github/workflows/jobs-api-
images.yml.
explorer-jes is a Zowe App Server Framework plug-in but does not have a built-in web service. It
follows Zowe's container conformance criteria. It defines a Dockerfile at
https://github.com/zowe/explorer-jes/blob/v2.x/master/container/Dockerfile. Similar to jobs-api , it
 also defines a GitHub Actions workflow at https://github.com/zowe/explorer-
jes/blob/v2.x/master/.github/workflows/build_test.yml to build the images.
The following GitHub Actions are used by the core components to build conformant images. They might not
be completely reusable for you, but are provided as an example.
zowe-actions/shared-actions/docker-prepare will prepare required environment variables used by
following steps.
zowe-actions/shared-actions/docker-build-local can build the Docker image directory on the GitHub
Actions virtual machine. By default, the Docker image directory is ubuntu-latest . You can use this
action to build images for amd64 CPU architecture.
zowe-actions/shared-actions/docker-build-zlinux can build Docker image on a Linux on Z virtual
machine. This is useful if you want to build images for s390x CPU architecture.
zowe-actions/shared-actions/docker-manifest can collect all related images and define them as Docker
manifests. This is useful for users to automatically pull the correct image based on cluster node CPU
architecture, and also pull images based on popular tags such as latest and latest-ubuntu .
After a component image is built, it is recommended that you publish it to a container registry before adding
it to the Zowe container environment. Alternatively, you can use docker save and docker load
commands to copy the offline images to your Kubernetes nodes.

2. Define Deployment or Job object

To start your component in Kubernetes, you must define a Deployment if your extension has built-in web
services, or a Job object if your extension is a Zowe Application Framework plug-in without built-in web
services.
To define Deployment for your component, you can copy from samples/sample-deployment.yaml
and modify all occurrences of the following variables:
<my-component-name> : this is your component name. For example, sample-node-api .

<my-component-image> : this is your component image described in Build and publish an extension
image to a registry. For example, zowe-docker-release.jfrog.io/ompzowe/sample-node-
api:latest-ubuntu .

<my-component-port> : this is the port of your service. For example, 8080 .

Continue to customize the specification to fit in your component requirements:

 spec.template.spec.containers[0].resources : defines the memory and CPU resource
required to start the container.
metadata.annotations , spec.template.spec.volumes and
spec.template.spec.securityContext and so on.

To define Job for your component, you can also copy from samples/sample-deployment.yaml .
Then, modify all entries mentioned above and make the following changes:
Change kind: Deployment to kind: Job ,
Add restartPolicy: OnFailure under spec.template.spec like this:

3. Start your component

After you define your component Deployment or Job object, you can run kubectl apply -f
/path/to/your/component.yaml to apply it to the Kubernetes cluster that runs Zowe.

If it's a Deployment , you should be able to see that the component pod is started and eventually
reached the Running status.
If it's a Job , you should be able to see that the plug-in pod is started and eventually reached the
Completed status.

Now you can follow common Kubernetes practice to manage your component workload.
Zowe Containerization Conformance Criteria
Version: v2.0.x LTS

These conformance criteria are applicable for all Zowe components intending to run in a containerized
environment. The containerized environment could be Kubernetes or OpenShift running on Linux or Linux on
Z.

Image
In general, the image should follow Best practices for writing Dockerfiles. The below requirements are in
addition to the list.
Base Image
You are free to choose a base image based on your requirements.
Here are our recommendations of base images:
Zowe base images:
ompzowe/base : zowe-docker-release.jfrog.io/ompzowe/base:latest-ubuntu and
zowe-docker-release.jfrog.io/ompzowe/base:latest-ubi .

ompzowe/base-node : zowe-docker-release.jfrog.io/ompzowe/base-node:latest-
ubuntu and zowe-docker-release.jfrog.io/ompzowe/base-node:latest-ubi has
node.js LTS (v14) version pre-installed.
ompzowe/base-jdk : zowe-docker-release.jfrog.io/ompzowe/base-jdk:latest-
ubuntu and zowe-docker-release.jfrog.io/ompzowe/base-jdk:latest-ubi has JRE
v8 pre-installed.
Red Hat Universal Base Image 8 Minimal
Ubuntu
The image should contain as few software packages as possible for security and should be as small as
possible such as by reducing package count and layers.
Zowe base images,
are based on both Ubuntu and Red Hat Universal Base Image,
 provide common dependencies including JDK and/or node.js,
support both amd64 and s390x CPU architecture.
If you use your own base image other than Zowe base images, please check this list and make sure it is
compatible with Zowe runtime:
The default shell /bin/sh must be bash . If it's not, you can fix it by installing and overwriting
/bin/sh with the symbolic link of /bin/bash .

These softwares must exist in the image: date , awk , sed , xargs .
These softwares are optional but good to have: ping , dig , netstat .
Multi-CPU Architecture
Zowe core components must release images based on both amd64 and s390x CPU architecture.
Zowe core component images must use multiple manifests to define if the image supports multiple CPU
architectures.
Image Label
These descriptive labels are required in the Dockerfile: name , maintainer , vendor , version ,
release , summary , and description .

Example line:
Tag
Zowe core component image tags must be a combination of the following information in this format:
<version>-<linux-distro>[-<cpu-arch>][-sources][.<customize-build>] .

version: must follow semantic versioning or partial semantic versioning with major or major + minor. It
may also be latest or lts . For example, 1 , 1.23 , 1.23.0 , lts , latest , etc.
linux-distro: for example, ubi , ubuntu , etc.
cpu-arch: for example, amd64 , s390x , etc.
customize-build: string sanitized by converting non-letters and non-digits to dashes. For example,
pr-1234 , users-john-fix123 , etc.

Source Build: must be a string -sources appended to the end of the tag.
If this is a source build, the tag must contain full version number (major+minor+patch) information.
 Linux Distro information is recommended.
Must NOT contain customize build information.
For example: 1.23.0-ubi-sources .
For example, these are valid image tags:
latest
latest-ubuntu
latest-ubuntu-sources
latest-ubi
latest-ubi-sources
lts
lts-ubuntu
lts-ubi
1
1-ubuntu
1-ubi
1.23
1.23-ubuntu
1.23-ubi
1.23.0
1.23.0-ubuntu
1.23.0-ubuntu-amd64
1.23.0-ubuntu-sources
1.23.0-ubi
1.23.0-ubi-s390x
1.23.0-ubi-sources
1.23.0-ubuntu.pr-1234
1.23.0-ubi.users-john-test1
The same image tag pattern is recommended for Zowe extensions.
Files and Directories
These file(s) and folder(s) are REQUIRED for all Zowe components:
 /licenses folder holds all license-related files. It MUST include at least the license information for
current application. It's recommended to include a license notice file for all pedigree dependencies. All
licenses files must be in UTF-8 encoding.
/component/README.md provides information about the application for end-user.

/component/manifest.(yaml|yml|json) provides basic information of the component. The

format of this file is defined at Zowe component manifest. Components must use the same manifest file
as when it's running on z/OS.
These file(s) and folder(s) are recommended:
/component/bin/<lifecycle-scripts> must remain the same as what it is when running on
z/OS.
User zowe
In the Dockerfile, a zowe user and group must be created. The zowe user UID and group GID must
be defined as ARG and with default values of UID=20000 and GID=20000 . Example commands:
USER zowe must be specified before the first CMD or ENTRYPOINT .

If you use Zowe base images, zowe user and group are already created.
Multi-Stage Build
A multi-stage build is recommended to keep images small and concise. Learn more from Use multi-stage
builds.

Runtime
This section is mainly for information. No actions are required for components except where it's specified
explicitly.
The below sections are mainly targeting Kubernetes or OpenShift environments. Starting Zowe containers in
a Docker environment with docker-compose is in a planning stage and may change some of the
requirements.
General rules
Components MUST:
NOT be started as root user in the container.
listen to only ONE port in the container except for API Mediation Layer Gateway.
be cloud-vendor neutral and must NOT rely on features provided by a specific cloud vendor.
NOT rely on host information such as hostIP , hostPort , hostPath , hostNetwork ,
hostPID and hostIPC .

accept zowe.yaml as a configuration file, the same as when running on z/OS.

Persistent Volume(s)
This persistent volume MUST be created:
zowe-workspace mounted to /home/zowe/instance/workspace .

Files and Directories

In the runtime, the Zowe content is organized in this structure:
/home/zowe/runtime is a shared volume initialized by the zowe-launch-scripts container.

/home/zowe/runtime/components/<component-id> is a symbolic link to the /component

directory. <component-id> is the name entry defined in /component/manifest.
(yaml|yml|json) .

/home/zowe/instance/zowe.yaml is a Zowe configuration file and MUST be mounted from a

ConfigMap.
/home/zowe/instance/logs is the logs directory of Zowe instance. This folder will be created
automatically by zowe-launch-scripts container.
/home/zowe/instance/workspace is the persistent volume mounted to every Zowe component
container.
Components writing to this directory should be aware of the potential conflicts of same-time
writing by multiple instances of the same component.
Components writing to this directory must NOT write container-specific information to this
directory as it may potentially be overwritten by another container.
/home/zowe/keystore is the directory where certificate is mounted. With a typical setup (by using
zwe migrate for kubernetes command), this folder contains keystore.p12 ,
truststore.p12 , keystore.key , keystore.cer and ca.cer .
 Any confidential environment variables, for example, a Redis password, in zowe.yaml must be
extracted and stored as Secrets. These configurations must be imported back as environment
variables.
ConfigMap and Secrets
zowe.yaml must be stored in a ConfigMap and be mounted under /home/zowe/instance
directory.
All certificates must be stored in Secrets. Those files will be mounted under the
/home/zowe/keystore directory.

Secrets must be defined manually by a system administrator. Zowe Helm Chart and Zowe Operator do
NOT define the content of Secrets.
ompzowe/zowe-launch-scripts Image and initContainers
The zowe-docker-release.jfrog.io/ompzowe/zowe-launch-scripts:latest-ubuntu or
zowe-docker-release.jfrog.io/ompzowe/zowe-launch-scripts:latest-ubi image
contains necessary scripts to start Zowe components in Zowe context.
This image has a /component directory and it will be used to prepare /home/zowe/runtime and
/home/zowe/instance volumes to help Zowe component start.

In Kubernetes and OpenShift environments this step is defined with initContainers specification.
Command Override
Component CMD and ENTRYPOINT directives will be overwritten with the Zowe launch script used to
start it in Zowe context.
Components running in Zowe context requires to be started with bash with argument
/home/zowe/runtime/bin/internal/run-zowe.sh -c /home/zowe/instance . Here is
example start command:
Environment Variables
These runtime environment variable(s) are REQUIRED to start Zowe components.
ZWE_POD_NAMESPACE : holds the current Kubernetes namespace. This variable can be optional if the
service account automountServiceAccountToken attribute is true . The value of this variable
can be assigned to metadata.namespace (which default value is zowe ) in Pod spec section:
These runtime environment variable(s) are OPTIONAL to start Zowe components.
ZWE_POD_CLUSTERNAME : holds the Kubernetes cluster name. This variable has default value
cluster.local . If your cluster name is not default value, you should pass the variable to all
workloads. The value of this variable can be assigned in Pod spec section:

CI/CD
Build, Test and Release
Zowe core component and extension images MUST be built, tested, and released on their own
cadence.
The component CI/CD pipeline MUST NOT rely on the Zowe level CI/CD pipeline and Zowe release
schedule.
Zowe core component images must be tested. This includes starting the component and verifying the
runtime container works as expected.
It is recommended to build snapshot images before release. Zowe core components MUST publish
snapshot images to the zowe-docker-snapshot.jfrog.io registry with proper tags.
Zowe core component images MUST be released before Zowe is released.
Zowe core components MUST publish release images to both zowe-docker-release.jfrog.io
and Docker Hub registry under ompzowe/ prefix.
Release images MUST also update relevant major/minor version tags and the latest tag. For
example, when a component releases a 1.2.3 image, the component CI/CD pipeline MUST also tag
the image as 1.2 , 1 , and latest . Update the lts tag when it is applicable.
Zowe core component release images MUST be signed by Zowe committer(s).
Developing for Zowe CLI
Version: v2.0.x LTS

You can extend Zowe™ CLI by developing plug-ins and contributing code to the base Zowe CLI or existing
plug-ins.

How to contribute
You can contribute to Zowe CLI in the following ways:
Add new commands, options, or other improvements to the base CLI.
Develop a plug-in that users can install to Zowe CLI.
You might want to contribute to Zowe CLI to accomplish the following objectives:
Provide new scriptable functionality for yourself, your organization, or to a broader community.
Make use of Zowe CLI infrastructure (profiles and programmatic APIs).
Participate in the Zowe CLI community space.

Getting started
If you want to start working with the code immediately, review the Readme file in the Zowe CLI core
repository and the Zowe contribution guidelines. The zowe-cli-sample-plugin GitHub repository is a sample
plug-in that adheres to the guidelines for contributing to Zowe CLI projects.
Tutorials
Follow these tutorials to get started working with the sample plug-in:
. Setting up: Clone the project and prepare your local environment.
. Installing a plug-in: Install the sample plug-in to Zowe CLI and run as-is.
. Extending a plug-in: Extend the sample plug-in with a new by creating a programmatic API, definition,
and handler.
. Creating a new plug-in: Create a new CLI plug-in that uses Zowe CLI programmatic APIs and a diff
package to compare two data sets.
. Implementing user profiles: Implement user profiles with the plug-in.
Plug-in development overview
At a high level, a plug-in must have imperative-framework configuration (sample here). This
configuration is discovered by imperative-framework through the package.json imperative key.
A Zowe CLI plug-in will minimally contain the following:
. Programmatic API: Node.js programmatic APIs to be called by your handler or other Node.js
applications.
. Command definition: The syntax definition for your command.
. Handler implementation: To invoke your programmatic API to display information in the format that you
defined in the definition.
The following guidelines and documentation will assist you during development:
Imperative CLI Framework documentation
Imperative CLI Framework documentation is a key source of information to learn about the features of
Imperative CLI Framework (the code framework that you use to build plug-ins for Zowe CLI). Refer to these
supplementary documents during development to learn about specific features such as:
Auto-generated help
JSON responses
User profiles
Logging, progress bars, experimental commands, and more!
Contribution guidelines
The Zowe CLI contribution guidelines contain standards and conventions for developing Zowe CLI plug-ins.
The guidelines contain critical information about working with the code, running/writing/maintaining
automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates with
Zowe CLI properly:
For more information about ... See:
General guidelines that apply to contributing to Zowe CLI and Plug-ins Contribution Guidelines
 For more information about ... See:
Conventions and best practices for creating packages and plug-ins for Package and Plug-in
Zowe CLI Guidelines
Guidelines for running tests on Zowe CLI Testing Guidelines
Guidelines for running tests on the plug-ins that you build Plug-in Testing Guidelines
Versioning conventions for Zowe CLI and Plug-ins Versioning Guidelines
Setting up your development environment
Version: v2.0.x LTS

Before you follow the development tutorials for creating a Zowe™ CLI plug-in, follow these steps to set up
your environment.

Prerequisites
Install Zowe CLI.

Initial setup
To create your development space, clone and build zowe-cli-sample-plugin from source.
Before you clone the repository, create a local development folder named zowe-tutorial . You will clone
and build all projects in this folder.

Branches
There are two branches in the repository that correspond to different Zowe CLI versions. You can develop
two branches of your plug-in so that users can install your plug-in into @latest or @zowe-v2-lts CLI.
Developing for both versions will let you take advantage of new core features quickly and expose your plug-
in to a wider range of users.
The master branch of Sample Plug-in is compatible with the @zowe-v2-lts version of core CLI (Zowe
LTS release).
The master branch of Sample Plug-in is also compatible with the @latest version of core CLI (Zowe
Active Development release) at this time.
For more information about the versioning scheme, see Maintainer Versioning in the Zowe CLI repository.
Clone zowe-cli-sample-plugin and build from source
Clone the repository into your development folder to match the following structure:
Follow these steps:
. cd to your zowe-tutorial folder.
. git clone https://github.com/zowe/zowe-cli-sample-plugin
. cd to your zowe-cli-sample-plugin folder.
. git checkout master
. npm install
. npm run build
(Optional) Run the automated tests
We recommend running automated tests on all code changes. Follow these steps:
. cd to the __tests__/__resources__/properties folder.
. Copy example_properties.yaml to custom_properties.yaml .
. Edit the properties within custom_properties.yaml to contain valid system information for your
site.
. cd to your zowe-cli-sample-plugin folder
. npm run test

Next steps
After you complete your setup, follow the Installing the sample plug-in tutorial to install this sample plug-in
to Zowe CLI.
Installing the sample plug-in
Version: v2.0.x LTS

Before you begin, set up your local environment to install a plug-in.

Overview
This tutorial covers installing and running this bundled Zowe™ CLI plugin as-is (without modification), which
will display your current directory contents.
The plug-in adds a command to the CLI that lists the contents of a directory on your computer.

Installing the sample plug-in to Zowe CLI

To begin, cd into your zowe-tutorial folder.
Issue the following commands to install the sample plug-in to Zowe CLI:
zowe plugins install ./zowe-cli-sample-plugin

Viewing the installed plug-in

Issue zowe --help in the command line to return information for the installed zowe-cli-sample
command group:

Using the installed plug-in

To use the plug-in functionality, issue: zowe zowe-cli-sample list directory-contents :

Testing the installed plug-in

To run automated tests against the plug-in, cd into your zowe-tutorial/zowe-cli-sample-plugin
folder.
Issue the following command:

Next steps
You successfully installed a plug-in to Zowe CLI! Next, try the Extending a plug-in tutorial to learn about
developing new commands for this plug-in.
Extending a plug-in
Version: v2.0.x LTS

Before you begin, be sure to complete the Installing the sample plug-in tutorial.

Overview
This tutorial demonstrates how to extend the plug-in that is bundled with this sample by:
. Creating a Typescript interface for the Typicode response data
. Creating a programmatic API
. Creating a command definition
. Creating a command handler
We'll do this by using @zowe/imperative infrastructure to surface REST API data on our Zowe™ CLI
plug-in.
Specifically, we're going to show data from this URI by Typicode. Typicode serves sample REST JSON data
for testing purposes.
At the end of this tutorial, you will be able to use a new command from the Zowe CLI interface: zowe
zowe-cli-sample list typicode-todos

Completed source for this tutorial can be found on the typicode-todos branch of the zowe-cli-sample-
plugin repository.
Creating a Typescript interface for the Typicode response data
First, we'll create a Typescript interface to map the response data from a server.
Within zowe-cli-sample-plugin/src/api , create a folder named doc to contain our interface
(sometimes referred to as a "document" or "doc"). Within the doc folder, create a file named ITodo.ts .
The ITodo.ts file will contain the following:
Creating a programmatic API
Next, we'll create a Node.js API that our command handler uses. This API can also be used in any Node.js
application, because these Node.js APIs make use of REST APIs, Node.js APIs, other NPM packages, or
custom logic to provide higher level functions than are served by any single API.
Adjacent to the existing file named zowe-cli-sample-plugin/src/api/Files.ts , create a file
Typicode.ts .

Typicode.ts should contain the following:

The Typicode class provides two programmatic APIs, getTodos and getTodo , to get an array of
ITodo objects or a specific ITodo respectively. The Node.js APIs use @zowe/imperative
infrastructure to provide logging, parameter validation, and to call a REST API. See the Imperative CLI
Framework documentation for more information.
Exporting interface and programmatic API for other Node.js applications
Update zowe-cli-sample-plugin/src/index.ts to contain the following:
A sample invocation of your API might look similar to the following, if it were used by a separate, standalone
Node.js application:
Checkpoint one
Issue npm run build to verify a clean compilation and confirm that no lint errors are present. At this
point in this tutorial, you have a programmatic API that will be used by your handler or another Node.js
application. Next you'll define the command syntax for the command that will use your programmatic
Node.js APIs.
Creating a command definition
Within Zowe CLI, the full command that we want to create is zowe zowe-cli-sample list typicode-
todos . Navigate to zowe-cli-sample-plugin/src/cli/list and create a folder typicode-
todos . Within this folder, create TypicodeTodos.definition.ts . Its content should be as follows:

This describes the syntax of your command.

Defining command to list group
Within the file zowe-cli-sample-plugin/src/cli/list/List.definition.ts , add the following
code below other import statements near the top of the file:
Then add TypicodeTodosDefinition to the children array. For example:
Creating a command handler
Also within the typicode-todos folder, create TypicodeTodos.handler.ts . Add the following code
to the new file:
The if statement checks if a user provides an --id flag. If yes, we call getTodo . Otherwise, we call
getTodos . If the Typicode API throws an error, the @zowe/imperative infrastructure will automatically
surface this.
Checkpoint two
Issue npm run build to verify a clean compilation and confirm that no lint errors are present. You now
have a handler, definition, and your command has been defined to the list group of the command.

Using the installed plug-in

Issue the command: zowe zowe-cli-sample list typicode-todos
Refer to zowe zowe-cli-sample list typicode-todos --help for more information about your
command and to see how text in the command definition is presented to the end user. You can also see how
to use your optional --id flag:

Summary
You extended an existing Zowe CLI plug-in by introducing a Node.js programmatic API, and you created a
command definition with a handler. For an official plugin, you would also add JSDoc to your code and create
automated tests.

Next steps
Try the Developing a new plug-in tutorial next to create a new plug-in for Zowe CLI.
Developing a new plug-in
Version: v2.0.x LTS

Before you begin this tutorial, complete the Extending an existing plug-in tutorial.

Overview
This tutorial demonstrates how to create a brand new Zowe™ CLI plug-in that uses Zowe CLI Node.js
programmatic APIs.
At the end of this tutorial, you will have created a data set diff utility plug-in for Zowe CLI, from which you can
pipe your plugin's output to a third-party utility for a side-by-side diff of data set member contents.

Completed source for this tutorial can be found on the develop-a-plugin branch of the zowe-cli-
sample-plugin repository.
Cloning the sample plug-in source
Clone the sample repo, delete the irrelevant source, and create a brand new plug-in. Follow these steps:
. cd into your zowe-tutorial folder
. git clone https://github.com/zowe/zowe-cli-sample-plugin files-util
. cd files-util
. Delete the .git (hidden) folder.
. Delete all content within the src/api , src/cli , and docs folders.
. Delete all content within the __tests__/__system__/api , __tests__/__system__/cli ,
__tests__/api , and __tests__/cli folders

. git init
. git add .
. git commit -m "initial"
Changing package.json
Use a unique npm name for your plugin. Change package.json name field as follows:
Issue the command npm install against the local repository.
Adjusting Imperative CLI Framework configuration
Change imperative.ts to contain the following:
Here we adjusted the description and other fields in the imperative JSON configuration to be relevant to
this plug-in.
Adding third-party packages
We'll use the following packages to create a programmatic API:
npm install --save diff

npm install -D @types/diff

Creating a Node.js programmatic API

In files-util/src/api , create a file named DataSetDiff.ts . The content of DataSetDiff.ts
should be the following:
Exporting your API
In files-util/src , change index.ts to contain the following:

Checkpoint
At this point, you should be able to rebuild the plug-in without errors via npm run build . You included
third party dependencies, created a programmatic API, and customized this new plug-in project. Next, you'll
define the command to invoke your programmatic API.
Defining commands
In files-util/src/cli , create a folder named diff . Within the diff folder, create a file
Diff.definition.ts . Its content should be as follows:

Also within the diff folder, create a folder named data-sets . Within the data-sets folder create
DataSets.definition.ts and DataSets.handler.ts .
DataSets.definition.ts should contain:
DataSets.handler.ts should contain the following:

Trying your command

Be sure to build your plug-in via npm run build .
Install your plug-in into Zowe CLI via zowe plugins install .
Issue the following command. Replace the data set names with valid mainframe data set names on your
system:

The raw diff output is displayed as a command response:

Bringing together new tools!

The advantage of Zowe CLI and of the CLI approach in mainframe development is that it allows for
combining different developer tools for new and interesting uses.
diff2html is a free tool to generate HTML side-by-side diffs to help see actual differences in diff output.
Install the diff2html CLI via npm install -g diff2html-cli . Then, pipe your Zowe CL plugin's
output into diff2html to generate diff HTML and launch a web browser that contains the content in the
screen shot at the top of this file.
zowe files-util diff data-sets "kelda16.work.jcl(iefbr14)"
"kelda16.work.jcl(iefbr15)" | diff2html -i stdin

Next steps
Try the Implementing profiles in a plug-in tutorial to learn about using profiles with your plug-in.
Implementing profiles in a plug-in
Version: v2.0.x LTS

You can use this profile template to create a profile for your product.
The profile definition is placed in the imperative.ts file.
The type: "someproduct" property represents the profile name that you might require on various
commands to have credentials loaded from a secure credential manager and retain the host/port
information, so that you can easily swap to different servers from the CLI.
By default, if your plug-in that is installed into Zowe™ CLI contains a profile definition that is similar to the
following example, a profile template is added automatically to team config JSON when you run the zowe
config init command. Any properties for which includeInTemplate is true are included in the
template. Additionally, commands that manage V1 profiles are created automatically under zowe
profiles . For example, create , validate , set-default , list , and so on.

Next steps
If you completed all previous tutorials, you now understand the basics of extending and developing plug-ins
for Zowe CLI. Next, we recommend reviewing the project contribution guidelines and Imperative CLI
Framework documentation to learn more.
Onboarding Overview
Version: v2.0.x LTS

As an API developer, you can onboard a REST API service to the Zowe™ API Mediation Layer (API ML).
Onboarding your REST service to the Zowe™ API Mediation Layer will make your service discoverable by the
API ML Discovery Service, enable routing through the API Gateway, and make service information and API
documentation available through the API Catalog.
The specific method you use to onboard a REST API to the API ML depends on the programming language
or framework used to build your REST service.
Note: To streamline the process of onboarding new REST API services to the Zowe API Mediation Layer, see
Onboarding a REST API service with the YAML Wizard
This Onboarding Overview article addresses the following topics:
Prerequisites
Service Onboarding Guides to onboard your REST service with the API ML
Verify successful onboarding to the API ML
Using the Sample REST API Service to learn how to onboard a REST service to the API ML

Prerequisites
Meet the following prerequisites before you onboard your service:
Running instance of Zowe
Note: For static onboarding, access to Zowe runtime is required to create the static service definition.
A certificate that is trusted by Zowe and certificate(s) to trust Zowe services
Zowe uses secured communication over TLSv1.2. As such, the protocol version and the certificate is
required. For more information, see API Mediation Layer security setup and Zowe API ML TLS
requirements.
A REST API-enabled service that you want to onboard
If you do not have a specific REST API service, you can use the sample service.
 Your service should be documented in a valid OpenApi 2.0/3.0 Swagger JSON format.
Access to the Zowe artifactory
Either the Gradle or Maven build automation system

Service Onboarding Guides

Services can be updated to support the API Mediation Layer natively by updating the service code. Use one
of the following guides to onboard your REST service to the Zowe API Mediation Layer:
Recommended guides for services using Java
Onboard a REST API service with the Plain Java Enabler (PJE)
Onboard a Spring Boot based REST API Service
Onboard a Micronaut based REST API service
Recommended guides for services using Node.js
Onboard a Node.js based REST API Service
Guides for Static Onboarding and Direct Call Onboarding
Use one of the following guides if your service is not built with Java, or you do not want to change your
codebase or use the previously mentioned libraries:
Onboard a REST API using static definition without code changes
Onboard a REST API directly calling Zowe Discovery Service
Documentation for legacy enablers
For legacy enabler documentation (version 1.2 and lower), refer to the previous version of the
documentation:
Zowe Docs version 1.8.x
Note: Enabler version 1.2 and previous versions are no longer supported.
Tip: We recommend you use the enabler version 1.3 or higher to onboard your REST API service to the Zowe
API Medaition Layer.

Verify successful onboarding to the API ML

Verifying that your service was successfully onboraded to the API ML can be done by ensuring service
registration in the API ML Discovery Service or visibility of the service in the API ML Catalog.
Verifying service discovery through Discovery Service
Verify that your service is discovered by the Discovery Service with the following procedure.
Follow these steps:
. Issue a HTTP GET request to the Discovery Service endpoint /eureka/apps to get service instance
information:
Note: The endpoint is protected by client certificate verification. A valid trusted certificate must be
provided with the HTTP GET request.
. Check your service metadata.
Response example:
Tips:
Ensure that addresses and user credentials for individual API ML components correspond to your
target runtime environment.
If you work with local installation of API ML and you use our dummy identity provider, enter user
for both username and password . If API ML was installed by system administrators, ask them
to provide you with actual addresses of API ML components and the respective user credentials.
Verifying service discovery through the API Catalog
Services may not be immediately visible in the API Catalog. We recommend you wait for 2 minutes as it may
take a moment for your service to be visible in the Catalog. If your service still does not appear in the
Catalog, ensure that your configuration settings are correct.
Follow these steps:
 . Check to see that your API service is displayed in the API Catalog UI, and that all information including
API documentation is correct.
. Ensure that you can access your API service endpoints through the Gateway.

Sample REST API Service

To demonstrate the concepts that apply to REST API services, we use an example of a Spring Boot REST API
service. This example is used in the REST API onboarding guide REST APIs without code changes required
(static onboarding).
You can build this service using instructions in the source code of the Spring Boot REST API service
example.
The Sample REST API Service has a base URL. When you start this service on your computer, the service
base URL is: http://localhost:8080 .
Note: If a service is deployed to a web application server, the base URL of the service (application) has the
following format: https://application-server-hostname:port/application-name .
This sample service provides one API that has the base path /v2 , which is represented in the base URL of
the API as http://localhost:8080/v2 . In this base URL, /v2 is a qualifier of the base path that was
chosen by the developer of this API. Each API has a base path depending on the particular implementation
of the service.
This sample API has only one single endpoint:
/pets/{id} - Find pet by ID.

This endpoint in the sample service returns information about a pet when the {id} is between 0 and 10. If
{id} is greater than 0 or a non-integer, an error is returned. These are conditions set in the sample
service.
Tip: Access http://localhost:8080/v2/pets/1 to see what this REST API endpoint does. You should get the
following response:
Note: The onboarding guides demonstrate how to add the Sample REST API Service to the API Mediation
Layer to make the service available through the petstore service ID.
The following diagram shows the relations between the Sample REST API Service and its corresponding API,
REST API endpoint, and API Gateway:
API Gateway API Gateway routes
/api/v2/petstore HTTP requests to /v2 of the API in the petstore service

«Service»
petstore

«API»
/v2
/pets

The petstore service provides one API (/v2)

This service runs in its own embedded web server

This sample service provides a Swagger document in JSON format at the following URL:
The Swagger document is used by the API Catalog to display API documentation.
Onboarding a REST API service with the Plain
Version: v2.0.x LTS

Java Enabler (PJE)

This article is part of a series of onboarding guides, which outline the process of onboarding REST API
services to the Zowe API Mediation Layer (API ML). As a service developer, you can onboard a REST service
with the API ML with the Zowe API Mediation Layer using our Plain Java Enabler (PJE). This enabler is built
without a dependency on Spring Cloud, Spring Boot, or SpringFramework.
Tip: For more information about onboarding API services with the API ML, see the Onboarding Overview.

Introduction
Zowe API ML is a lightweight API management system based on the following Netflix components:
Eureka - a discovery service used for services registration and discovery
Zuul - reverse proxy / API Gateway
Ribbon - load balancer
The API ML Discovery Service component uses Netflix/Eureka as a REST services registry. Eureka endpoints
are used to register a service with the API ML Discovery Service.
The API ML provides onboarding enabler libraries. The libraries are JAR artifacts available through an
artifactory. Using these libraries is the recommended approach to onboard a REST service with the API ML.
The PJE library serves the needs of Java developers who are not using either Spring Boot or the Spring
Framework. If Spring Boot or the Spring framework are used in the project you would like to onboard, see the
Onboarding Overview for the corresponding enablers.
Additionally, this enabler is not intended for use in projects that depend on Spring Cloud Netflix components.
Configuration settings in the PJE and Spring Cloud Netflix Eureka Client are different. Using the two
configuration settings in combination makes the result state of the discovery registry unpredictable.
Tip: For more information about how to utilize another API ML enablers, see the documentation in the
Onboarding Overview.
Onboarding your REST service with API ML
The following steps outline the overall process to onboard a REST service with the API ML using the PJE.
Each step is described in further detail in this article.
. Prerequisites
. Configuring your project
Gradle build automation system
Maven build automation system
. Configuring your service
REST service identification
Administrative endpoints
API info
API routing information
API Catalog information
Authentication parameters
API Security
SAF Keyring configuration
Eureka Discovery Service
. Registering your service with API ML
. (Optional) Validating the discoverability of your API service by the Discovery Service
. (Optional) Troubleshooting
Log messages during registration problems

Prerequisites
Ensure that the prerequisites from the Onboarding Overview are met.
The REST API service to onboard is written in Java
 The service is enabled to communicate with API ML Discovery Service over a TLS v1.2 secured
connection
Notes:
This documentation is valid for API ML version ZoweApimlVersion 1.3.0 and higher. We
recommend that you check the Zowe Artifactory for latest stable versions.
Following this guide enables REST services to be deployed on a z/OS environment. Deployment to a
z/OS environment, however, is not required. As such, you can first develop on a local machine before
you deploy on z/OS.
The API Mediation Layer provides the sample application using the Plain Java Enabler in the api-layer
repository

Configuring your project

Use either Gradle or Maven build automation systems to configure the project with the service to be
onboarded. Use the appropriate configuration procedure that corresponds to your build automation system.
Note: You can use either the Zowe Artifactory or an artifactory of your choice. If you decide to build the API
ML from source, you are required to publish the enabler artifact to your artifactory. Publish the enabler
artifact by using the Gradle tasks provided in the source code.
Gradle build automation system
Use the following procedure to use Gradle as your build automation system.
Follow these steps:
. Create a gradle.properties file in the root of your project if one does not already exist.
. In the gradle.properties file, set the URL of the specific artifactory containing the PJE artifact.
Provide the corresponding credentials to gain access to the Maven repository.
. Add the following Gradle code block to the repositories section of your build.gradle file:
. In the same build.gradle file, add the necessary dependencies for your service. If you use the Java
enabler from the Zowe Artifactory, add the following code block to your build.gradle script.
 Replace the $zoweApimlVersion with the proper version of the enabler, for example: 1.3.0 :
The published artifact from the Zowe Artifactory also contains the enabler dependencies from other
software packages. If you are using an artifactory other than Zowe, add also the following dependencies
in your service build.gradle script:
Notes:
You may need to add more dependencies as required by your service implementation.
The information provided in this file is valid for ZoweApimlVersion 1.3.0 and higher.
. In your project home directory, run the gradle clean build command to build your project.
Alternatively, you can run gradlew to use the specific gradle version that is working with your project.
Maven build automation system
Use the following procedure if you use Maven as your build automation system.
Follow these steps:
. Add the following XML tags within the newly created pom.xml file:
Tip: If you want to use snapshot version, replace libs-release with libs-snapshot in the
repository url and change snapshots->enabled to true .
. Add the proper dependencies:
. In the directory of your project, run the mvn clean package command to build the project.

Configuring your service

To configure your service, create the configuration file service-configuration.yml in your service
source tree resources directory. The default path for a java application is src/main/resources . The
service-configuration.yml file is used to set the application properties and eureka metadata.
Application properties are for your service runtime. For example, the ssl section specifies the keystore
and trustore. The eureka metadata is used for registration with API Mediation Layer.
Note: To externalize service onboarding configuration, see: Externalizing onboarding configuration.
The following code snippet shows an example of service-configuration.yml . Some parameters
which are specific for your service deployment are in ${parameterValue} format. For your service
configuration file, provide actual values or externalize your onboarding configuration.
Example:
Optional metadata section
The following snippet presents additional optional metadata that can be added.
Example:
The onboarding configuration parameters are broken down into the following groups:
REST service identification
Administrative endpoints
API info
API routing information
API catalog information
Authentication parameters
API security
SAF Keyring configuration
Eureka Discovery Service
Custom Metadata
Connection Timeout
REST service identification
serviceId
The serviceId uniquely identifies one or more instance of a microservice in the API ML and is used
as part of the service URL path in the API ML Gateway address space. Additionally, the API ML Gateway
uses the serviceId for routing to the API service instances. When two API services use the same
serviceId , the API Gateway considers the services as clones of each other. An incoming API request
can be routed to either of them through utilized load balancing mechanism.
Important! Ensure that the serviceId is set properly with the following considerations:
 The same servicedId should only be set for multiple API service instances for API scalability.
The servicedId value must only contain lowercase alphanumeric characters.
The servicedId cannot contain more than 40 characters.
Example:
If the serviceId is sampleservice , the service URL in the API ML Gateway address space
appears as the following path:
title
This parameter specifies the human readable name of the API service instance. This value is displayed
in the API Catalog when a specific API service instance is selected. This parameter can be externalized
and set by the customer system administrator.
Tip: We recommend that service developer provides a default value of the title . Use a title that
describes the service instance so that the end user knows the specific purpose of the service instance.
description
This parameter is a short description of the API service. This value is displayed in the API Catalog when
a specific API service instance is selected. This parameter can be externalized and set by the customer
system administrator.
Tip: Describe the service so that the end user understands the function of the service.
baseUrl
This parameter specifies the base URL for the following administrative endpoints:
homePageRelativeUrl
statusPageRelativeUrl
healthCheckRelativeUrl
Use the following format to include your service name in the URL path:
protocol://host:port/servicename
 Note: Ensure that the baseUrl does not end with a trailing / . Inclusion of / causes a
malformed URL if any of the above administrative endpoints begin with a / . It is expected that
each administrative endpoint begins with a / . Warnings will be logged if this recommendation is
not followed.
serviceIpAddress (Optional)
This parameter specifies the service IP address and can be provided by a system administrator in the
externalized service configuration. If this parameter is not present in the configuration file or is not set
as a service context parameter, it is resolved from the hostname part of the baseUrl .
preferIpAddress (Optional)
Set the value of this parameter to true to advertise a service IP address instead of its hostname.
Administrative endpoints
The following snippet presents the format of the administrative endpoint properties:
where:
homePageRelativeUrl
specifies the relative path to the home page of your service.
Start this path with / . If your service has no home page, leave this parameter blank.
Examples:
homePageRelativeUrl: This service has no home page
homePageRelativeUrl: / This service has a home page with URL ${baseUrl}/

statusPageRelativeUrl
specifies the relative path to the status page of your service.
Start this path with / .
Example:
statusPageRelativeUrl: /application/info
 This results in the URL: ${baseUrl}/application/info
healthCheckRelativeUrl
specifies the relative path to the health check endpoint of your service.
Start this path with / .
Example:
healthCheckRelativeUrl: /application/health

This results in the URL: ${baseUrl}/application/health

API info
REST services can provide multiple APIs. Add API info parameters for each API that your service wants to
expose on the API ML.
The following snippet presents the information properties of a single API:
where:
apiInfo.apiId
specifies the API identifier that is registered in the API ML installation. The API ID uniquely identifies the
API in the API ML. The apiId can be used to locate the same APIs that are provided by different
service instances. The API developer defines this ID. The apiId must be a string of up to 64
characters that uses lowercase alphanumeric characters and a dot: . .
apiInfo.version
specifies the api version . This parameter is used to correctly retrieve the API documentation
according to requested version of the API.
apiInfo.gatewayUrl
specifies the base path at the API Gateway where the API is available. Ensure that this value is the same
path as the gatewayUrl value in the routes sections that apply to this API.
apiInfo.swaggerUrl (Optional)
 specifies the Http or Https address where the Swagger JSON document is available.
apiInfo.documentationUrl (Optional)
specifies the link to the external documentation. A link to the external documentation can be included
along with the Swagger documentation.
apiInfo.defaultApi (Optional)
specifies that this API is the default one shown in the API Catalog. If no apiInfo fields have
defaultApi set to true , the default API is the one with the highest API version .

API routing information

The API routing group provides the required routing information used by the API ML Gateway when routing
incoming requests to the corresponding REST API service. A single route can be used to direct REST calls to
multiple resources or API endpoints. The route definition provides rules used by the API ML Gateway to
rewrite the URL in the Gateway address space. Currently, the routing information consists of two parameters
per route: The gatewayUrl and serviceUrl . These two parameters together specify a rule for how the
API service endpoints are mapped to the API Gateway endpoints.
The following snippet is an example of the API routing information properties.
Example:
where:
routes
specifies the container element for the route.
routes.gatewayUrl
The gatewayUrl parameter specifies the portion of the gateway URL which is replaced by the
serviceUrl path part.

routes.serviceUrl
The serviceUrl parameter provides a portion of the service instance URL path which replaces the
gatewayUrl part.
Examples:
is routed to:
API major version 1:
is routed to:
APIs docs major version 1:
is routed to:
API Catalog information
The API ML Catalog UI displays information about discoverable REST services registered with the API ML
Discovery Service. Information displayed in the Catalog is defined by the metadata provided by your service
during registration. The following image is an example of a tile in the API Catalog:

The Catalog groups correlated services in the same tile if these services are configured with the same
catalog.tile.id metadata parameter.

The following code block is an example of configuration of a service tile in the Catalog:
Example:
where:
catalog.tile.id
specifies the unique identifier for the product family of API services. This is a value used by the API ML
to group multiple API services into a single tile. Each unique identifier represents a single API dashboard
tile in the Catalog.
Tip: Specify a value that does not interfere with API services from other products. We recommend that
you use your company and product name as part of the ID.
catalog.tile.title
 specifies the title of the product family of the API service. This value is displayed in the API Catalog
dashboard as the tile title.
catalog.tile.description
is the detailed description of the API services product family. This value is displayed in the API Catalog
UI dashboard as the tile description.
catalog.tile.version
specifies the semantic version of this API Catalog tile.
Note: Ensure that you increase the version number when you introduce changes to the API service
product family details.
Authentication parameters
These parameters are not required. Default values are used when parameters are not specified. For more
information, see Authentication Parameters for Onboarding REST API Services.
API Security
REST services onboarded with the API ML act as both a client and a server. When communicating to API ML
Discovery service, a REST service acts as a client. When the API ML Gateway is routing requests to a
service, the REST service acts as a server. These two roles have different requirements. The Zowe API ML
Discovery Service communicates with its clients in secure Https mode. As such, TLS/SSL configuration
setup is required when a service is acting as a server. In this case, the system administrator decides if the
service will communicate with its clients securely or not.
Client services need to configure several TLS/SSL parameters in order to communicate with the API ML
Discovery service. When an enabler is used to onboard a service, the configuration is provided in the ssl
section/group in the same YAML file that is used to configure the Eureka parameters and the service
metadata.
For more information about API ML security, see API ML security.
TLS/SSL configuration consists of the following parameters:
verifySslCertificatesOfServices
This parameter makes it possible to prevent server certificate validation.
Important! Ensure that this parameter is set to true in production environments. Setting this
parameter to false in production environments significantly degrades the overall security of the
system.
protocol
This parameter specifies the TLS protocol version currently used by Zowe API ML Discovery Service.
Tip: We recommend you use TLSv1.2 as your security protocol
keyAlias
This parameter specifies the alias used to address the private key in the keystore.
keyPassword
This parameter specifies the password associated with the private key.
keyStore
This parameter specifies the keystore file used to store the private key. When using keyring, the value
should be set to the SAF keyring location. For information about required certificates, see Zowe API ML
TLS requirements.
If you have an issue with loading the keystore file in your environment, try to provide the absolute path
to the keystore file. The sample keystore file for local deployment is in api-layer repository
keyStorePassword
This parameter specifies the password used to unlock the keystore.
keyStoreType
This parameter specifies the type of the keystore.
trustStore
This parameter specifies the truststore file used to keep other parties public keys and certificates.
When using keyring, this value should be set to the SAF keyring location. For information about required
 certificates, see Zowe API ML TLS requirements.
If you have an issue with loading the truststore file in your environment, try to provide the absolute path
to the truststore file. The sample truststore file for local deployment is in api-layer repository
trustStorePassword: password
This parameter specifies the password used to unlock the truststore.
trustStoreType: PKCS12
This parameter specifies the truststore type. The default for this parameter is PKCS12.
Note: Ensure that you define both the keystore and the truststore even if your server is not using an Https
port.
SAF Keyring configuration
You can choose to use SAF keyring instead of keystore and truststore for storing certificates. For information
about required certificates, see Zowe API ML TLS requirements. For information about running Java on z/OS
with keyring, see SAF Keyring. Make sure that the enabler can access and read the keyring. Please refer to
documentation of your security system for details.
The following example shows enabler configuration with keyrings.
Example:
Eureka Discovery Service
The Eureka Discovery Service parameters group contains a single parameter used to address Eureka
Discovery Service location. An example is presented in the following snippet:
Example:
where:
discoveryServiceUrls
Specifies the public URL of the Discovery Service. The system administrator at the customer site
defines this parameter. It is possible to provide multiple values in order to utilize fail over and/or load
balancing mechanisms.
Custom Metadata
For information about custom metadata, see the topic Custom Metadata.

Registering your service with API ML

The following steps outline the process of registering your service with API ML. Each step is described in
detail in this article. The process describes the integration with the usage of the Java application server. The
guideline is tested with the Tomcat application server. The specific steps that apply for other application
servers may differ.
. Add a web application context listener class
. Register a web application context listener
. Load service configuration
. Register with Eureka discovery service
. Unregister your service
Follow these steps:
. Implement and add a web application context listener class:
implements javax.servlet.ServletContextListener

The web application context listener implements two methods to perform necessary actions at
application start-up time as well as when the application context is destroyed:
The contextInitialized method invokes the apiMediationClient.register(config)
method to register the application with API Mediation Layer when the application starts.
The contextDestroyed method invokes the apiMediationClient.unregister()
method when the application shuts down. This unregisters the application from the API Mediation
Layer.
. Register a web application context listener.
Add the following code block to the deployment descriptor web.xml to register a context listener:
. Load the service configuration.
 Load your service configuration from a file service-configuration.yml file. The configuration
parameters are described in the preceding section, Configuring your service.
Use the following code as an example of how to load the service configuration.
Example:
Note: The ApiMediationServiceConfigReader class also provides other methods for loading the
configuration from two files, java.util.Map instances, or directly from a string. Check the
ApiMediationServiceConfigReader class JavaDoc for details.

. Register with Eureka Discovery Service.

Use the following call to register your service instance with Eureka Discovery Service:
Example:
. Unregister your service.
Use the contextDestroyed method to unregister your service instance from Eureka Discovery
Service in the following format:
Example:
The following code block is a full example of a context listener class implementation.
Example:

Validating the discoverability of your API service by the

Discovery Service
Once you are able to build and start your service successfully, you can use the option of validating that your
service is registered correctly with the API ML Discovery Service.
Follow these steps:
. Validate successful onboarding
. Check that you can access your API service endpoints through the Gateway.
 . (Optional) Check that you can access your API service endpoints directly outside of the Gateway.
Specific addresses and user credentials for the individual API ML components depend on your target
runtime environment.
Note: If you are working with local installation of API ML and you are using our dummy identity provider,
enter user for both username and password . If API ML was installed by system administrators, ask
them to provide you with actual addresses of API ML components and the respective user credentials.
Tip: Wait for the Discovery Service to discover your service. This process may take a few minutes after your
service was successfully started.

Troubleshooting
Log messages during registration problems
When an Enabler connects to the Discovery service and fails, an error message prints to the Enabler log. The
default setting does not suppress these messages as they are useful to resolve problems during the Enabler
registration. Possible reasons for failure include the location of Discovery service is not correct, the
Discovery Service is down, or the TLS certificate is invalid.
These messages continue to print to the Enabler log, while the Enabler retries to connect to the Discovery
Service. To fully suppress these messages in your logging framework, set the log levels to OFF on the
following loggers:
Some logging frameworks provide other tools to suppress repeated messages. Consult the documentation
of the logging framework you use to find out what tools are available. The following example demonstrates
how the Logback framework can be used to suppress repeated messages.
Example:
The Logback framework provides a filter tool, DuplicateMessageFilter.
Add the following code to your configuration file if you use XML configuration:
Note: For more information, see the full configuration used in the Core Services in GitHub.
API Mediation Layer onboarding
Version: v2.0.x LTS

configuration
This article describes the process of configuring a REST service to onboard with the Zowe API Mediation
Layer using the API ML Plain Java Enabler. As a service developer, you can provide basic configuration of a
service to onboard to the API ML. You can also externalize configuration parameters for subsequent
customization by a systems administrator.
Introduction
Configuring a REST service for API ML onboarding
Plain Java Enabler service onboarding
Automatic initialization of the onboarding configuration by a single method call
Validating successful onboarding with the API Mediation Layer
Loading YAML configuration files
Loading a single YAML configuration file
Loading and merging two YAML configuration files

Introduction
The API ML Plain Java Enabler (PJE) is a library which helps to simplify the process of onboarding a REST
service with the API ML. This article describes how to provide and externalize the Zowe API ML onboarding
configuration of your REST service using the PJE.
Note: For more information about specific configuration parameters and their possible values, and the
service registration process, see the specific documentation of the onboarding approach you are using for
your project:
Direct REST call registration (No enabler)
Plain Java Enabler
The PJE is the most universal Zowe API ML enabler. This enabler uses only Java, and does not use advanced
Inversion of Control (IoC) or Dependency Injection (DI) technologies. The PJE enables you to onboard any
REST service implemented in Java, avoiding dependencies, versions collisions, unexpected application
behavior, and unnecessarily large service executables.
Service developers provide onboarding configuration as part of the service source code. While this
configuration is valid for the development system environment, it is likely to be different for an automated
integration environment. Typically, system administrators need to deploy a service on multiple sites that have
different system environments and requirements such as security.
The PJE supports both the service developer and the system administrator with the functionality of
externalizing the service onboarding configuration.
The PJE provides a mechanism to load API ML onboarding service configuration from one or two YAML files.

Configuring a REST service for API ML onboarding

In most cases, the API ML Discovery Service, Gateway, and service endpoint addresses are not known at the
time of building the service executables. Similarly, security material such as certificates, private/public keys,
and their corresponding passwords depend on the specific deployment environment, and are not intended
to be publicly accessible. Therefore, to provide a higher level of flexibility, the PJE implements routines to
build service onboarding configuration by locating and loading one or two YAML file sources:
internal service-configuration.yml
The first configuration file is typically internal to the service deployment artifact. This file must be
accessible on the service classpath . This file contains basic API ML configuration based on values
known at development time. Usually, this basic API ML configuration is provided by the service
developer and is located in the /resources folder of the Java project source tree. This file is usually
found in the deployment artifacts under /WEB-INF/classes . The configuration contained in this file
is provided by the service developer or builder. As such, it will not match every possible production
environment and its corresponding requirements.
external or additional service-configuration.yml
The second configuration file is used to externalize the configuration. This file can be stored anywhere
on the local file system, as long as that the service has access to that location. This file is provided by
the service deployer/system administrator and contains the correct parameter values for the specific
production environment.
At service start-up time, both YAML configuration files are merged, where the externalized configuration (if
provided) has higher priority.
The values of parameters in both files can be rewritten by Java system properties or servlet context
parameters that were defined during service installation/configuration, or at start-up time.
In the YAML file, standard rewriting placeholders for parameter values use the following format:
${apiml.parameter.key}

The actual values are taken from [key, value] pairs defined as Java system properties or servlet context
parameters. The system properties can be provided directly on a command line. The servlet context
parameters can be provided in the service web.xml or in an external file.
The specific approach of how to provide the servlet context to the user service application depends on the
application loading mechanism and the specific Java servlet container environment.
Example:
If the service is deployed in a Tomcat servlet container, you can configure the context by placing an XML file
with the same name as the application deployment unit into
_$CATALINA_BASE/conf/[enginename]/[hostname]/_ .

Other containers provide different mechanisms for the same purpose.

Plain Java Enabler service onboarding API

You can initialize your service onboarding configuration using different methods of the Plain Java Enabler
class ApiMediationServiceConfigReader :
Automatic initialization of the onboarding configuration by a single method call
The following code block shows automatic initialization of the onboarding configuration by a single method
call:
This method receives the ServletContext parameter, which holds a map of parameters that provide all
necessary information for building the onboarding configuration. The following code block is an example of
Java Servlet context configuration.
Example:
Where the two parameters corresponding to the location of the configuration files are:
 apiml.config.location

This parameter describes the location of the basic configuration file.

apiml.config.additional-location

This parameter describes the location of the external configuration file.

The method in this example uses the provided configuration file names in order to load them as YAML
files into the internal Java configuration object of type ApiMediationServiceConfig.
The other context parameters with the apiml prefix are used to rewrite values of properties in the
configuration files.

Validating successful onboarding with the API Mediation

Layer
Ensure that you successfully onboarded a service with the API Mediation Layer.
Follow these steps:
. Validate successful onboarding
. Check that you can access your API service endpoints through the Gateway.
. (Optional) Check that you can access your API service endpoints directly outside of the Gateway.
Loading YAML configuration files
YAML configuration files can be loaded either as a single YAML file, or by merging two YAML files. Use the
loadConfiguration method described later in this article that corresponds to your service
requirements.
After successfully loading a configuration file, the loading method loadConfiguration uses Java system
properties to substitute corresponding configuration properties.
Loading a single YAML configuration file
To build your configuration from multiple sources, load a single configuration file, and then rewrite
parameters as needed using values from another configuration source. See: Loading and merging two YAML
configuration files described later in this article.
Use the following method to load a single YAML configuration file:
This method receives a single String parameter and can be used to load an internal or an external
configuration file.
Note: This method first attempts to load the configuration as a Java resource. If the file is not found, the
method attempts to resolve the file name as an absolute. If the file name still cannot be found, this method
attempts to resolve the file as a relative path. When the file is found, the method loads the contents of the
file and maps them to internal data classes. After loading the configuration file, the method attempts to
substitute/rewrite configuration property values with corresponding Java System properties.
Loading and merging two YAML configuration files
To load and merge two configuration files, use the following method:
where:
String internalConfigurationFileName
references the basic configuration file name.
String externalizedConfigurationFileName
references the external configuration file name.
Note: The external configuration file takes precedence over the basic configuration file in order to match the
target deployment environment. After loading and before merging, each configuration will be separately
patched using Java System properties.
The following code block presents an example of how to load and merge onboarding configuration from
YAML files.
Example:
Onboarding a service with the Zowe API
Version: v2.0.x LTS

Meditation Layer without an onboarding

enabler
This article is part of a series of guides to onboard a REST service with the Zowe API Mediation Layer (API
ML). Onboarding with API ML makes services accessible through the API Gateway and visible in the API
Catalog. Once a service is successfully onboarded, users can see if the service is currently available and
accepting requests.
This guide describes how a REST service can be onboarded with the Zowe API ML independent of the
language used to write the service. As such, this guide does not describe how to onboard a service with a
specific enabler. Similarly, various Eureka client implementations are not used in this onboarding method.
Tip: If possible, we recommend that you onboard your service using the API ML enabler libraries. The
approach described in this article should only be used if other methods to onboard your service are not
suitable.
For more information about how to onboard a REST service, see the following links:
API ML onboarding overview
python-eureka-client
eureka-js-client
Rest API developed based on Java
This article outlines a process to make an API service available in the API Mediation Layer by making a direct
call to the Eureka Discovery Service.
Introduction
Registering with the Discovery Service
API Mediation Layer Service onboarding metadata
Catalog parameters
Service parameters
Routing parameters
API Info Parameters
Sending a heartbeat to API Mediation Layer Discovery Service
 Validating successful onboarding with the API Mediation Layer
External Resources

Introduction
The API ML Discovery Service uses Netflix/Eureka as a REST services registry. Eureka is a REST-based
service that is primarily used to locate services.
Eureka endpoints are used to register a service with the API ML Discovery Service. Endpoints are also used
to send a periodic heartbeat to the Discovery Service to indicate that the onboarded service is available.
Note: Required parameters should be defined and sent at registration time.

Registering with the Discovery Service

Begin the onboarding process by registering your service with the API ML Discovery Service.
Use the POST Http call to the Eureka server together with the registration configuration in the following
format:
The following code block shows the format of the parameters in your POST call, which are sent to the
Eureka registry at the time of registration.
where:
app
uniquely identifies one or more instances of a microservice in the API ML.
The API ML Gateway uses the serviceId for routing to the API service instances. As such, the
serviceId is part of the service URL path in the API ML Gateway address space.

Important! Ensure that the service ID is set properly with the following considerations:
The service ID value contains only lowercase alphanumeric characters.
The service ID does not contain more than 40 characters.
 The same service ID is only set for multiple API service instances to support API scalability. When
two API services use the same service ID, the API Gateway considers the services as clones of
each other. An incoming API request can be routed to either instance through load balancing.
Example:
If the serviceId is sampleservice , the service URL in the API ML Gateway address space
appears as:
ipAddr
specifies the IP address of this specific service instance.
port
specifies the port of the instance when you use Http. For Http, set enabled to true .
securePort
specifies the port of the instance for when you use Https. For Https, set enabled to true .
hostname
specifies the hostname of the instance.
vipAddress
specifies the serviceId when you use Http.
Important! Ensure that the value of vipAddress is the same as the value of app . Furthermore, be
sure not to omit vipAddress , even if you provided secureVipAddress . Due to a current limitation
in Spring Cloud Netflix, routes are created only for instances in which vipAddress is defined.
secureVipAddress
specifies the serviceId when you use Https.
Important! Ensure that the value of secureVipAddress is the same as the value of app .
instanceId
 specifies a unique id for the instance. Define a unique value for the instanceId in the following
format:
{hostname}:{serviceId}:{port}

metadata
specifies the set of parameters described in the following section addressing API ML service metadata.
API Mediation Layer Service onboarding metadata
At registration time, provide metadata in the following format. Metadata parameters contained in this code
block are described in the following section.
Metadata parameters are broken down into the following categories:
Catalog parameters
Service parameters
Routing parameters
Authentication parameters
API Info parameters
Catalog parameters
Catalog parameters are grouped under the prefix: apiml.catalog.tile .
The API ML Catalog displays information about services registered with the API ML Discovery Service.
Information displayed in the Catalog is defined in the metadata provided by your service during registration.
The Catalog groups correlated services in the same tile when these services are configured with the same
catalog.tile.id metadata parameter.

The following parameters are used to populate the API Catalog:

apiml.catalog.tile.id
This parameter specifies the specific identifier for the product family of API services. This is a value
used by the API ML to group multiple API services into a single tile. Each identifier represents a single
API dashboard tile in the Catalog.
 Important! Specify a value that does not interfere with API services from other products. We
recommend that you use your company and product name as part of the ID.
apiml.catalog.tile.title
This parameter specifies the title of the API services product family. This value is displayed in the API
Catalog dashboard as the tile title.
apiml.catalog.tile.description
This parameter is the detailed description of the API services product family. This value is displayed in
the API Catalog UI dashboard as the tile description.
apiml.catalog.tile.version
This parameter specifies the semantic version of this API Catalog tile.
Note: Ensure that you increase the version number when you introduce changes to the API service
product family details.
Service parameters
Service parameters are grouped under the prefix: apiml.service
The following parameters define service information for the API Catalog:
apiml.service.title
This parameter specifies the human-readable name of the API service instance.
This value is displayed in the API Catalog when a specific API service instance is selected.
apiml.service.description
This parameter specifies a short description of the API service.
This value is displayed in the API Catalog when a specific API service instance is selected.
apiml.enableUrlEncodedCharacters
When this parameter is set to true , the Gateway allows encoded characters to be part of URL
requests redirected through the Gateway. The default setting of false is the recommended setting.
Change this setting to true only if you expect certain encoded characters in your application's
requests.
Important! When the expected encoded character is an encoded slash or backslash ( %2F , %5C ),
make sure the Gateway is also configured to allow encoded slashes. For more info see Installing the
Zowe runtime on z/OS.
apiml.connectTimeout
The value in milliseconds that specifies a period in which API ML should establish a single, non-
managed connection with this service. If omitted, the default value specified in the API ML Gateway
service configuration is used.
apiml.readTimeout
The value in milliseconds that specifies maximum time of inactivity between two packets in response
from this service to API ML. If omitted, the default value specified in the API ML Gateway service
configuration is used.
apiml.connectionManagerTimeout
HttpClient employs a special entity to manage access to HTTP connections called by HTTP connection
manager. The purpose of an HTTP connection manager is to serve as a factory for new HTTP
connections, to manage the life cycle of persistent connections, and to synchronize access to
persistent connections. Internally, an HTTP connection manager works with managed connections,
which serve as proxies for real connections. ConnectionManagerTimeout specifies a period in
which managed connections with API ML should be established. The value is in milliseconds. If omitted,
the default value specified in the API ML Gateway service configuration is used.
apiml.okToRetryOnAllOperations
Specifies whether all operations can be retried for this service. The default value is false . The
false value allows retries for only GET requests if a response code of 503 is returned. Setting this
value to true enables retry requests for all methods, which return a 503 response code. Enabling
retry can impact server resources resulting from buffering of the request body.
apiml.service.corsEnabled
When this parameter is set to true , CORS is enabled on the service level for all service routes. The
same parameter can also be set on the service level, by providing the parameter as customMetadata
 as shown in the Custom Metadata.
apiml.response.compress
When this parameter is set to true , API ML compresses content for all responses from these services
using GZIP. API ML also adds the Content-Encoding header with the value gzip to responses.
customMetadata.apiml.response.compressRoutes
When the customMetadata.apiml.response.compress parameter is set to true , this
parameter allows the services to further limit the compressed routes. The parameter accepts ant style
routes deliminated by , . The expectation is to provide the absolute paths. If relative paths are
provided, the starting / is added. If the beginning of the pattern does not require specification, use
**/{pathYouAreInterestedIn}

Examples
/service/**

Compresses all paths starting with /service/

/service/api/v1/compress,/service/api/v1/custom-compress

Compresses the specific two routes

/\*\*/compress/\*\*

Compresses all paths that contain compress as a specific path

Routing parameters
Routing parameters are grouped under the prefix: apiml.routes
The API routing group provides necessary routing information used by the API ML Gateway when routing
incoming requests to the corresponding service. A single route can be used to make direct REST calls to
multiple resources or API endpoints. The route definition provides rules used by the API ML Gateway to
rewrite the URL in the Gateway address space.
Routing information consists of two parameters per route:
gatewayUrl
 serviceUrl

These two parameters together specify a rule of how the API service endpoints are mapped to the API
Gateway endpoints.
The following snippet is an example of the API routing information properties.
Example:
where:
apiml.routes.{route-prefix}.gatewayUrl
The gatewayUrl parameter specifies the portion of the gateway URL which is replaced by the
serviceUrl path.

apiml.routes.{route-prefix}.serviceUrl
The serviceUrl parameter provides a portion of the service instance URL path which replaces the
gatewayUrl part.

Note: The routes configuration used for a direct REST call to register a service must also contain a prefix
before the gatewayUrl and serviceUrl . This prefix is used to differentiate the routes. This prefix must
be provided manually when XML configuration is used.
For more information about API ML routing, see API Gateway Routing.
Authentication parameters
Authentication parameters are grouped under the prefix: apiml.authentication . When unspecified,
the default values are used.
This parameter enables a service to accept the Zowe JWT token. The API Gateway translates the token to
an authentication method supported by a service.
The following parameters define the service authentication method:
apiml.authentication.scheme
This parameter specifies a service authentication scheme. The following schemes are supported by the
API Gateway:
bypass
This value specifies that the token is passed unchanged to the service.
Note: This is the default scheme when no authentication parameters are specified.
zoweJwt
This value specifies that a service accepts the Zowe JWT token. No additional processing is done
by the API Gateway.
httpBasicPassTicket
This value specifies that a service accepts PassTickets in the Authorization header of the HTTP
requests using the basic authentication scheme. It is necessary to provide a service APPLID in the
apiml.authentication.applid parameter.

Tip: For more information, see Enabling PassTicket creation for API Services that Accept
PassTickets.
zosmf
This value specifies that a service accepts z/OSMF LTPA (Lightweight Third-Party Authentication).
This scheme should only be used for a z/OSMF service used by the API Gateway Authentication
Service, and other z/OSMF services that are using the same LTPA key.
Tip: For more information about z/OSMF Single Sign-on, see Establishing a single sign-on
environment.
safIdt
This value specifies that the application recognizes the SAF IDT scheme and fills the X-SAF-
Token header with the token produced by the Saf IDT provider implementation.

For more information, see SAF IDT provider

x509
This value specifies that a service accepts client certificates forwarded in the HTTP header. The
Gateway service extracts information from a valid client certificate. For validation, the certificate
needs to be trusted by API Mediation Layer, and needs to contain a Client Authentication
 (1.3.6.1.5.5.7.3.2) entry in Extended Key Usage. To use this scheme, it is also necessary to specify
which headers to include. Specify these parameters in headers .
zosmf
This value specifies that a service accepts z/OSMF LTPA (Lightweight Third-Party Authentication).
This scheme should only be used for a z/OSMF service used by the API Gateway Authentication
Service, and other z/OSMF services that are using the same LTPA key.
Tip: For more information about z/OSMF Single Sign-on, see Establishing a single sign-on
environment.
authentication.headers
When the x509 scheme is specified, use the headers parameter to select which values to send to a
service. Use one of the following values:
X-Certificate-Public

The public part of the client certificate base64 encoded

X-Certificate-DistinguishedName

The distinguished name the from client certificate

X-Certificate-CommonName

The common name from the client certificate

apiml.authentication.applid
This parameter specifies a service APPLID. This parameter is valid only for the
httpBasicPassTicket authentication scheme.

API Info parameters

API Info parameters are grouped under the prefix: apiml.apiInfo .
REST services can provide multiple APIs. Add API info parameters for each API that your service wants to
expose on the API ML. These parameters provide information for API (Swagger) documentation that is
displayed in the API Catalog.
The following parameters provide the information properties of a single API:
apiml.apiInfo.{api-index}.apiId
The API ID uniquely identifies the API in the API ML. Multiple services can provide the same API. The API
ID can be used to locate the same APIs that are provided by different services. The creator of the API
defines this ID. The API ID needs to be a string of up to 64 characters that uses lowercase alphanumeric
characters and a dot: . .
Tip: We recommend that you use your organization as the prefix.
apiml.apiInfo.{api-index}.version
This parameter specifies the API version. This parameter is used to correctly retrieve the API
documentation according to the requested version of the API.
apiml.apiInfo.{api-index}.gatewayUrl
This parameter specifies the base path at the API Gateway where the API is available. Ensure that this
value is the same path as the gatewayUrl value in the routes sections for the routes, which
belong to this API.
apiml.apiInfo.{api-index}.swaggerUrl
(Optional) This parameter specifies the Http or Https address where the Swagger JSON document is
available.
apiml.apiInfo.{api-index}.documentationUrl
(Optional) This parameter specifies the link to the external documentation. A link to the external
documentation can be included along with the Swagger documentation.
apiml.apiInfo.{api-index}.defaultApi
(Optional) This parameter specifies if the API is the default one shown in the API Catalog. If no API has
this parameter set to true , or multiple APIs have it set to true , then the default API becomes the
API with the highest major version seen in apiml.apiInfo.{api-index}.version .
Note: The {api-index} is used to differentiate the service APIs. This index must be provided manually
when XML configuration is used. In the following example, 0 represents the api-index .
Sending a heartbeat to API Mediation Layer Discovery
Service
After registration, a service must send a heartbeat periodically to the Discovery Service to indicate that the
service is available. When the Discovery Service does not receive a heartbeat, the service instance is
deleted from the Discovery Service.
If the server does not receive a renewal in 90 seconds, it removes the instance from its registry.
Note: We recommend that the interval for the heartbeat is no more than 30 seconds.
Use the Http PUT method in the following format to tell the Discovery Service that your service is available:
https://{eureka_hostname}:{eureka_port}/eureka/apps/{serviceId}/{instanceId}

Validating successful onboarding with the API Mediation

Layer
Ensure that you successfully onboarded a service with the API Mediation Layer.
Follow these steps:
. Validate successful onboarding
. Check that you can access your API service endpoints through the Gateway.
. (Optional) Check that you can access your API service endpoints directly outside of the Gateway.

External Resources
https://blog.asarkar.org/technical/netflix-eureka/
https://medium.com/@fahimfarookme/the-mystery-of-eureka-health-monitoring-5305e3beb6e9
https://github.com/Netflix/eureka/wiki/Eureka-REST-operations
Onboarding a Spring Boot based REST API
Version: v2.0.x LTS

Service
This guide is part of a series of guides to onboard a REST API service with the Zowe API Mediation Layer. As
an API developer, you can onboard your REST API service built with the Spring Boot framework with the
Zowe API Mediation Layer.
Note: Before API ML version 1.2, the API ML provided an integration enabler based on Spring Cloud Netflix
components. From version 1.3 and later, the API ML uses a new implementation based on the Plain Java
Enabler (PJE) that is not backwards compatible with the previous enabler versions. API ML core services
(Discovery Service, Gateway, and API Catalog) support both the old and new enabler versions.
Tip: For more information about how to utilize another onboarding method, see:
Onboard a REST API service with the Plain Java Enabler (PJE)
Onboard a REST service directly calling eureka with xml configuration
Onboard an existing REST API service without code changes

Outline of onboarding a REST service using Spring Boot

The following steps outline the overall process to onboard a REST service with the API ML using a Spring
Boot enabler. Each step is described in further detail in this article.
. Selecting a Spring Boot Enabler
. Configuring your project
Gradle build automation system
Maven build automation system
. Configuring your Spring Boot based service to onboard with API ML
Sample API ML Onboarding Configuration
Authentication properties
API ML Onboarding Configuration Sample
SAF Keyring configuration
 Custom Metadata
Api Mediation Layer specific metadata
. Registering and unregistering your service with API ML
Unregistering your service with API ML
Basic routing
. Adding API documentation
. (Optional) Validating the discoverability of your API service by the Discovery Service
. (Optional) Troubleshooting
Log messages during registration problems

Selecting a Spring Boot Enabler

Add a dependency on the Spring Enabler version to your project build configuration that corresponds to the
Spring Boot version that you use for the whole project:
onboarding-enabler-spring-v1
onboarding-enabler-spring-v2
Note: The process of onboarding an API service is the same for both Spring Boot enabler versions.

Configuring your project

Use either Gradle or Maven as your build automation system to manage your project builds.
Note: You can download the selected enabler artifact from the Zowe Artifactory for latest stable versions..
Alternatively, if you decide to build the API ML from source, it is necessary to publish the enabler artifact to
your Artifactory. Publish the enabler artifact by using the Gradle tasks provided in the source code.
Gradle build automation system
Use the following procedure to use Gradle as your build automation system.
Follow these steps:
 . Create a gradle.properties file in the root of your project if one does not already exist.
. In the gradle.properties file, set the URL of the specific Artifactory containing the SpringEnabler
artifact.
. Add the following Gradle code block to the repositories section of your build.gradle file:
. In the same build.gradle file, add the necessary dependencies for your service. If you use the
SpringEnabler from the Zowe Artifactory, add the following code block to your build.gradle script:
Use the corresponding artifact according to the Zowe APIML version you are using.
For Zowe APIML versions greater than 1.23.5 use the following artifact:
For Zowe APIML version 1.23.5 use the following artifact:
For Zowe APIML versions 1.22.3, 1.22.4, and 1.23.0 - 1.23.4 use the following artifact:
For Zowe APIML versions 1.21.6 - 1.21.13 and 1.22.0 - 1.22.2 use the following artifact:
For Zowe APIML versions earlier than 1.21.6 that use Spring 2.1.1 use the following artifact:
For Zowe APIML versions earlier than 1.21.6 that use Spring 1.5.9 use the following artifact:
Notes:
You may need to add additional dependencies as required by your service implementation.
The information provided in this file is valid for ZoweApimlVersion 1.3.0 and above.
. In your project home directory, run the gradle clean build command to build your project.
Alternatively, you can run gradlew to use the specific gradle version that is working with your project.
Maven build automation system
Use the following procedure if you use Maven as your build automation system.
Follow these steps:
. Add the following XML tags within the newly created pom.xml file:
 Tip: If you want to use snapshot version, replace libs-release with libs-snapshot in the repository url
and change snapshots->enabled to true.
. Add the proper dependencies
For Zowe APIML versions greater than 1.23.5 use the following artifact:
For Zowe APIML version 1.23.5 use the following artifact:
For Zowe APIML versions 1.22.3, 1.22.4, and 1.23.0 - 1.23.4 use the following artifact:
For Zowe APIML versions 1.21.6 - 1.21.13 and 1.22.0 - 1.22.2 use the following artifact:
For Zowe APIML versions earlier than 1.21.6 that use Spring 2.1.1 use the following artifact:
For Zowe APIML versions earlier than 1.21.6 that use Spring 1.5.9 use the following artifact:
. In the directory of your project, run the mvn clean package command to build the project.

Configuring your Spring Boot based service to onboard with

API ML
To configure a Spring Boot based service, it is useful to first understand how API ML enabled service Spring
Boot based configuration relates to configuration using the Plain Java Enabler.
Spring Boot expects to find the default configuration of an application in an application.yml file that is
placed on the classpath. Typically application.yml contains Spring Boot specific properties such as
properties that are used to start a web application container including TLS security, different spring
configuration profiles definitions, and other properties. This application.yml must contain the Plain
Java Enabler API ML service configuration under the apiml.service prefix. The API ML configuration
under this prefix is necessary to synchronize the configuration of apiml.service with the spring
server configuration.

Configuration properties belong to two categories:

Service related properties which include endpoints, relative paths, or API documentation definitions.
Environment related properties which include host names, ports, context etc.
Execution environment related properties should be provided by additional configuration mechanisms that
are specific to the target execution environment. Execution environment related properties for development
deployments on a local machine differ with those properties on a mainframe system.
In a development environment, provide execution environment related properties in an additional
YAML file with the system property in the following format:

On the mainframe system, provide additional configuration properties and values for existing
configuration properties through Java system properties.
Execution environments for local development deployments and mainframe deployment are described
in detail later in this article.
Follow these steps:
. Provide a configuration section for onboarding with API ML in the application.yml file.
If you have already onboarded your service with API ML, copy and paste the contents of your
existing API ML onboarding configuration file. The default of the API ML onboarding configuration
file is the service-configuration.yml in the application.yml file under the
apiml.service prefix.

If you have not yet onboarded your REST service with API ML, use the Sample API Onboarding
Configuration to get started.
. If you are reusing your existing API ML onboarding configuration, modify the API ML related properties
of the application.yml file.
a) Remove certain properties under the apiml.service section, which must be externalized.
Properties for removal are described in the following sample of API ML onboarding configuration.
b) Provide the following additional properties under the apiml section:
These additional properties are contained in the following sample.
Sample API ML Onboarding Configuration
In the following sample API ML onboarding configuration, properties prefixed with ### (3 hashtags)
indicate that their value must be provided as -Dsystem.property.key=PROPERTY_VALUE defined in the
mainframe execution environment. The -Dsystem.property.key must be the same as the flattened
path of the YAML property which is commented out with ### . These properties must not be defined
(uncommented) in your default service YAML configuration file.
Example:
In this example from the YAML configuration file, when the application service is run on the mainframe,
provide your mainframe hostname value on the Java execution command line in the following format:
Since this value is provided in the Java execution command line, leave the property commented out in the
application.yml .

For development purposes, you can replace or add any property by providing the same configuration
structure in an external YAML configuration file. When running your application, provide the name of the
external/additional configuration file on the command line in the following format:
A property notation provided in the format -Dproperty.key=PROPERTY_VALUE can be used for two
purposes:
To provide a runtime value for any YAML property if ${property.key} is used as its value (after
: ) in the YAML configuration file

Example:
To add a property to configuration if the property does not already exist
Example:
Note: System properties provided with -D notation on the command line will not replace properties
defined in any of the YAML configuration files.
Authentication properties
These parameters are not required. If a parameter is not specified, a default value is used. See
Authentication Parameters for Onboarding REST API Services for more details.
API ML Onboarding Configuration Sample
Some parameters which are specific for your service deployment are written in
${fill.your.parameterValue} format. For your service configuration file, provide actual values or
externalize your configuration using -D java commandline parameters.
Tip: To determine if your configuration is complete, set the logging level to debug and run your
application. Setting the logging level to 'debug' enables you to troubleshoot issues with certificates for
HTTPS and connections with other services.
. Provide the suitable parameter corresponding to your runtime environment:
For a local machine runtime environment, provide the following parameter on your command line:
At runtime, Spring will merge the two YAML configuration files, whereby the properties in the external
file have higher priority.
For a mainframe execution environment, provide environment specific configuration properties. Define
these configuration properties and provide them using Java System Properties on the application
execution command line.
Important! Ensure that the default configuration contains only properties which are not dependent on
the deployment environment. Do not include security sensitive data in the default configuration.
Note: For details about the configuration properties, see Configuring your service in the article
Onboarding a REST API service with the Plain Java Enabler (PJE).
SAF Keyring configuration
You can choose to use a SAF keyring instead of keystore and truststore for storing certificates. For
information about required certificates, see Zowe API ML TLS requirements. For information about running
Java on z/OS with a keyring, see SAF Keyring. Make sure that the enabler can access and read the keyring.
Please refer to documentation of your security system for details.
The following example shows enabler configuration with keyrings:
Custom Metadata
Custom metadata are described here.

Registering and unregistering your service with API ML

Onboarding a REST service to the API ML means registering the service with the API ML Discovery Service.
The registration is triggered automatically by Spring after the service application context is fully initialized by
firing a ContextRefreshed event.
To register your REST service with API ML using a Spring Boot enabler, annotate your application main
class with @EnableApiDiscovery .
Unregistering your service with API ML
Unregistering a service onboarded with API ML is done automatically at the end of the service application
shutdown process in which Spring fires a ContextClosed event. The Spring onboarding enabler listens
for this event and issues an unregister REST call to the API ML Discovery Service.
Basic routing
See API ML Basic Routing for more information about basic routing in the API ML.

Adding API documentation

Use the following procedure to add Swagger API documentation to your project.
Follow these steps:
. Add a SpringFox Swagger dependency.
For Gradle, add the following dependency in build.gradle :
For Maven, add the following dependency in pom.xml :
. Add a Spring configuration class to your project.
Example:
. Customize this configuration according to your specifications. For more information about
customization properties, see Springfox documentation.
Note: The current SpringFox Version 2.9.2 does not support OpenAPI 3.0. For more information about
the open feature request see this issue.

Validating the discoverability of your API service by the

Discovery Service
Once you build and start your service successfully, you can use the option of validating that your service is
registered correctly with the API ML Discovery Service.
Follow these steps:
. Validate successful onboarding
. Check that you can access your API service endpoints through the Gateway.
. (Optional) Check that you can access your API service endpoints directly outside of the Gateway.
Specific addresses and user credentials for the individual API ML components depend on your target
runtime environment.
Note: If you are working with local installation of API ML and you are using our dummy identity provider,
enter user for both username and password . If API ML was installed by system administrators, ask
them to provide you with actual addresses of API ML components and the respective user credentials.
Tip: Wait for the Discovery Service to fully register your service. This process may take a few minutes after
your service was successfully started.

Troubleshooting
Log messages during registration problems
When an Enabler connects to the Discovery Service and fails, an error message prints to the Enabler log.
The default setting does not suppress these messages as they are useful to resolve problems during the
Enabler registration. Possible reasons for failure include the location of Discovery Service is not correct, the
Discovery Service is down, or the TLS certificate is invalid. These messages continue to print to the Enabler
log, while the Enabler retries to connect to the Discovery Service.
To fully suppress these messages in your logging framework, set the log levels to OFF on the following
loggers:
Some logging frameworks provide other tools to suppress repeated messages. Consult the documentation
of the logging framework you use to find out what tools are available. The following example demonstrates
how the Logback framework can be used to suppress repeated messages.
Example:
The Logback framework provides a filter tool, DuplicateMessageFilter.
Add the following code to your configuration file if you use XML configuration:
Note: For more information, see the full configuration used in the Core Services in GitHub.
Onboarding a Micronaut based REST API
Version: v2.0.x LTS

service
As an API developer, you can onboard a REST service to the Zowe API Mediation Layer using the Micronaut
framework. While using the Spring framework to develop a JVM-based service to register to the API ML is
the recommended method, you can use the procedure described in this article to onboard a service using
the Micronaut framework.
Note: For more information about onboarding API services with the API ML, see the Onboarding Overview.
For Micronaut-related documentation, see the Micronaut website.
Set up your build automation system
Specify the main class
Define the output jar file
(Optional) Create a shadow jar
Start the application
Configure the Micronaut application
Add API ML configuration
Add Micronaut configuration
Set up logging configuration
Validate successful registration

Set up your build automation system

Currently, the only build automation system for use with onboarding a Micronaut based service is Gradle.
Follow these steps:
. Create a gradle.properties file in the root of your project if one does not already exist.
. In the gradle.properties file, set the URL of the specific Artifactory containing the SpringEnabler
artifact.
. Add the following Gradle code block to the repositories section of your build.gradle file:
 . In the build.gradle file, add the micronaut enabler as a dependency:
. (Optional) Add a shadow plug-in to create a runnable jar file. Update the gradle.build file with a
plugin:
. Specify the main class with the following script:
. Define the output jar file.
Add the following script to define the output of the jar file:
The following example shows a sample gradle.build file:
Example:
. (Optional) Create a shadow jar.
To create a shadow jar, execute the gradle shadowJar task. For this sample, the plugin produces the
jar micronaut-enabler-1.0.jar in build/libs directory.
You can now run your application with the command java -jar micronaut-enabler-1.0.jar .
. Start the application.
From the root directory of your project, start the application with the gradle run command.

Configure the Micronaut application

Use a yaml file to configure your Micronaut application. Create the following two sections in your yaml file:
apiml for API ML configuration

micronaut for micronaut configuration

Add API ML configuration

Use the following procedure to add API ML configuration to the application.yaml.
Follow these steps:
. Add the following configuration to the apiml section in the yaml file:
 where:
fill.your.service

specifies the ID of your service

. Add SSL-resolving properties as shown in the following example. Ensure that you structure the nested
objects within apiml.service as arrays. Be sure to include - (hyphen) before enabled thereby
indicating the first element of the array.
Example:
Note: For a sample of this configuration, see API ML Onboarding Configuration Sample.
The yaml now contains configuration to register to the API Mediation Layer.
Add Micronaut configuration
Once you complete API ML configuration, add configuration to provide correct mapping between API ML
and micronaut parameters.
Follow these steps:
. Add the following yaml snippet with the micronaut configuration parameters:
where:
apiml.service.serviceId

specifies the ID of your service

apiml.service.port

specifies the port on which the service listens

apiml.service.ssl[0].keyPassword

specifies the password that protects the key in keystore

apiml.service.ssl[0].keyStoreType
 specifies the type of the keystore, (Example: PKCS12)
apiml.service.ssl[0].keyStore

specifies the location of the keystore

apiml.service.ssl[0].keyAlias

specifies the alias under which the key is stored in the keystore
apiml.service.ssl[0].trustStorePassword

specifies the password that protects the certificates in the truststore

apiml.service.ssl[0].trustStore

specifies the location of the truststore

apiml.service.ssl[0].trustStoreType

specifies the type of the truststore, (Example: PKCS12)

apiml.service.ssl[0].ciphers

specifies the list of ciphers that user wants to enable for TLS communication
apiml.service.ssl[0].protocol

specifies the type of SSL/TLS protocol (Example: TLSv1.2)

(Optional) Set up logging configuration
Set up custom logging configuration to have more structured output and better control of logs.
Create a logback.xml file in the resources folder and include the application.yml . Update the
logback.xml file with the following configuration:

Validate successful registration

After you complete the configuration, ensure that your application is visible within Zowe API ML. For more
information, see the article validating the discoverability of your API service by teh Discovery Service, which
describes the validation procedure common for all enablers.
Onboarding a Node.js based REST API
Version: v2.0.x LTS

service
This article is part of a series of onboarding articles, which outline the process of onboarding REST API
services to the Zowe API Mediation Layer (API ML). As a service developer, you can onboard a REST service
based on NodeJS with the API ML with the Zowe API Mediation Layer using our Node.js Enabler.
Note: For more information about onboarding API services with the API ML, see the Onboarding Overview.

Introduction
The API ML onboarding Node.js enabler is an NPM package which helps to simplify the process of
onboarding a REST service written in Node.js with the API ML.
For more information about how to utilize another API ML enablers, see the Onboarding Overview.

Onboarding your Node.js service with API ML

The following steps outline the overall process to onboard a REST service with the API ML using the
onboarding Node.js enabler. Each step is described in further detail in this article.
. Prerequisites
. Install the npm dependency
. Configure your service
. Register your service with API ML
. (Optional) Validate the discoverability of your API service by the Discovery Service

Prerequisites
Ensure that you meet the following prerequisites:
 You satisfy the prerequisites from the Onboarding Overview.
The REST API service to onboard is written in Node.js.
The service is enabled to communicate with API ML Discovery Service over a TLS v1.2 secured
connection.

Installing the npm dependency

Install the onboarding Node.js enabler package as a dependency of your service. Run the following npm
command from your project directory:
Note: If you have a multi-module project, you have to run the npm command from the submodule where
your Node.js project is located.

Configuring your service

Create a yaml file named service-configuration.yml inside a /config directory at the same level
of your index.js , and add the following configuration properties.
The following example shows a sample configuration.
Example:

Registering your service with API ML

To register your service with API ML, use the following procedure.
Follow these steps:
. Inside your Node.js service index.js , add the following code block to register your service with
Eureka:
. Start your Node.js service and verify that the service is registered to the Zowe API Mediation Layer.

Validating the discoverability of your API service by the

Discovery Service
Once you build and start your service successfully, you can use the option of validating that your service is
registered correctly with the API ML Discovery Service.
Follow these steps:
. Validate successful onboarding
. Check that you can access your API service endpoints through the Gateway.
. (Optional) Check that you can access your API service endpoints directly outside of the Gateway.
Specific addresses and user credentials for the individual API ML components depend on your target
runtime environment.
Note: If you are working with a local installation of API ML, and you are using our dummy identity provider,
enter user for both username and password . If API ML was installed by system administrators, ask
them to provide you with actual addresses of API ML components and the respective user credentials.
Note: Wait for the Discovery Service to fully register your service. This process may take a few minutes after
your service starts successfully.
Onboard a REST API without code changes
Version: v2.0.x LTS

required
As a user of Zowe™, onboard an existing REST API service to the Zowe™ API Mediation Layer without
changing the code of the API service. This form of onboarding is also refered to as, "static onboarding".
Note: When developing a new service, it is not recommended to onboard a REST service using this method,
as this method is non-native to the API Mediation Layer. For a complete list of methods to onboard a REST
service natively to the API Mediation Layer, see the Onboarding Overview.
The following procedure outlines the steps to onboard an API service through the API Gateway in the API
Mediation Layer without requiring code changes.
Identify the API that you want to expose
Define your service and API in YAML format
Route your API
Customize configuration parameters
Add and validate the definition in the API Mediation Layer running on your machine
Add a definition in the API Mediation Layer in the Zowe runtime
(Optional) Check the log of the API Mediation Layer
(Optional) Reload the services definition after the update when the API Mediation Layer is already
started
Tip: For more information about the structure of APIs and which APIs to expose in the Zowe API Mediation
Layer, see the Onboarding Overview.

Identify the APIs that you want to expose

The first step in API service onboarding is to identify the APIs that you want to expose.
Follow these steps:
. Identify the following parameters of your API service:
Hostname
 Port
(Optional) base path where the service is available. This URL is called the base URL of the service.
Example:
In the sample service described in the Onboarding Overview, the URL of the service is:
http://localhost:8080 .

. Identify the API of the service that you want to expose through the API Gateway.
Example:
The API provided by the sample service is a second version of the Pet Store API. All the endpoints to be
onboarded are available through http://localhost:8080/v2/ URL. This REST API is therefore
available at the path /v2 relative to base URL of the service. There is no version 1 in this case.
. Choose the service ID of your service. The service ID identifies the service uniquely in the API
Gateway. The service ID is an alphanumeric string in lowercase ASCII.
Example:
In the sample service, the service ID is petstore .
. Decide which URL to use to make this API available in the API Gateway. This URL is referred to as the
gateway URL and is composed of the API type and the major version. The usually used types are: api ,
ui and ws but you can use any valid URL element you want.

Example:
In the sample service, we provide a REST API. The first segment is /api as the service provides only
one REST API. To indicate that this is version 2, the second segment is /v2 . This version is required by
the Gateway. If your service does not have a version, use v1 on the Gateway.

Define your service and API in YAML format

After you identify the APIs you want to expose, you need to define your service and API in YAML format as
presented in the following sample petstore service example.
Example:
To define your service in YAML format, provide the following definition in a YAML file as in the following
sample petstore service. This configuration is the minimal configuration necessary for the Gateway to
properly route the requests to the application and to show the Service in the Catalog UI.
Note: For more details about configuration, see Customize configuration parameters.
In this example, a suitable name for the file is petstore.yml .
Notes:
The filename does not need to follow specific naming conventions but it requires the .yml extension.
The file can contain one or more services defined under the services: node.
Each service has a service ID. In this example, the service ID is petstore . The service id is used as a
part of the request URL towards the Gateway. It is removed by the Gateway when forwarding the
request to the service.
The service can have one or more instances. In this case, only one instance
http://localhost:8080 is used.

One API is provided and the requests with the relative base path api/v2 at the API Gateway (full
gateway URL: https://gateway:port/serviceId/api/v2/... ) are routed to the relative base
path /v2 at the full URL of the service ( http://localhost:8080/v2/... ).
The file on USS should be encoded in ASCII to be read correctly by the API Mediation Layer.
Tips:
There are more examples of API definitions at this link.
For more details about how to use YAML format, see this link.

Route your API

Routing is the process of sending requests from the API Gateway to a specific API service. Route your API by
using the same format as in the following petstore example. The configuration parameters are explained
in Customize configuration parameters. Gateway URL format:
Note: The API Gateway differentiates major versions of an API.
Example:
When the configuration parameters are:
To access API version 2 of the service petstore , gateway URL will be:
It will be routed to:
To access resource pets of the petstore version 2 API, gateway URL will be:
It will be routed to:
Note: This method enables you to access the service through a stable URL, and move the service to another
machine without changing the gateway URL. Accessing a service through the API Gateway also enables you
to have multiple instances of the service running on different machines to achieve high-availability.

Customize configuration parameters

This part contains a more complex example of the configuration and an explanation of all the possible
parameters:
serviceId
This parameter specifies the service instance identifier that is registered in the API Mediation Layer
installation. The service ID is used in the URL for routing to the API service through the Gateway. The
service ID uniquely identifies the service in the API Mediation Layer. The system administrator at the
customer site defines this parameter.
Important! Ensure that the service ID is set properly with the following considerations:
When two API services use the same service ID, the API Gateway considers the services to be
clones (i.e. two instances for the same service). An incoming API request can be routed to either of
them.
The same service ID should be set only for multiple API service instances for API scalability.
The service ID value must contain only lowercase alphanumeric characters.
The service ID cannot contain more than 40 characters.
 The service ID is linked to security resources. Changes to the service ID require an update of
security resources.
Examples:
If the customer system administrator sets the service ID to monitoringpr1 , the API URL in the
API Gateway appears as the following URL:
If customer system administrator sets the service ID to authenticationprod1 , the API URL in
the API Gateway appears as the following URL:
title
This parameter specifies the human readable name of the API service instance (for example,
Monitoring Prod or systemInfo LPAR1 ). This value is displayed in the API catalog when a
specific API service instance is selected. This parameter is externalized and set by the customer system
administrator.
Tip: We recommend that you provide a specific default value of the title . Use a title that describes
the service instance so that the end user knows the specific purpose of the service instance.
description
This parameter specifies a short description of the API service.
Examples:
Monitoring Service - Production Instance

System Info Service running on LPAR1

This value is displayed in the API Catalog when a specific API service instance is selected. This
parameter is externalized and set by the customer system administrator.
Tip: Describe the service so that the end user knows the function of the service.
instanceBaseUrls
This parameter specifies a list of base URLs to your service's REST resource. It will be the prefix for the
following URLs:
 homePageRelativeUrl
statusPageRelativeUrl
healthCheckRelativeUrl
Examples:
- http://host:port/ftpservice for an HTTP service
- https://host:port/source-code-mngmnt for an HTTPS service

You can provide one URL if your service has one instance. If your service provides multiple
instances for the high-availability then you can provide URLs to these instances.
Examples:
- https://host1:port1/source-code-mngmnt

- https://host2:port2/source-code-mngmnt

homePageRelativeUrl
This parameter specifies the relative path to the homepage of your service. The path should start with
/ . If your service has no homepage, omit this parameter. The path is relative to the instanceBaseUrls.

Examples:
homePageRelativeUrl: / The service has homepage with URL ${baseUrl}/

homePageRelativeUrl: /ui/ The service has homepage with URL ${baseUrl}/ui/

homePageRelativeUrl: The service has homepage with URL ${baseUrl}

statusPageRelativeUrl
This parameter specifies the relative path to the status page of your service. Start this path with / . If
you service doesn't have a status page, omit this parameter. The path is relative to the
instanceBaseUrls.
Example:
statusPageRelativeUrl: /application/info
the result URL will be:
${baseUrl}/application/info

healthCheckRelativeUrl
This parameter specifies the relative path to the health check endpoint of your service. Start this URL
with / . If your service does not have a health check endpoint, omit this parameter. The path is relative
to the instanceBaseUrls.
Example:
healthCheckRelativeUrl: /application/health

This results in the URL:

${baseUrl}/application/health

routes
The following parameters specify the routing rules between the Gateway service and your service. Both
specify how the API endpoints are mapped to the API Gateway endpoints.
routes.gatewayUrl
The gatewayUrl parameter sets the target endpoint on the Gateway. This is the portion of the final
URL that is Gateway specific.
Example:
For the petstore example, the full Gateway URL would be:
https://gatewayUrl:1345/petstore/api/v2/pets/1

In this case, the URL that will be called on the service is:
http://localhost:8080/v2/pets/1

routes.serviceRelativeUrl
The serviceRelativeUrl parameter points to the target endpoint on the service. This is the base path
on the service called through the Gateway.
authentication
Parameters under this grouping allow a service to accept the Zowe JWT token. The API Gateway
translates the token to an authentication method supported by a service.
authentication.scheme
This parameter specifies a service authentication scheme. The following schemes are supported
by the API Gateway:
bypass
This value specifies that the token is passed unchanged to the service. This is the default
scheme when no authentication parameters are specified.
zoweJwt
This value specifies that a service accepts the Zowe JWT token. No additional processing is
done by the API Gateway.
httpBasicPassTicket
This value specifies that a service accepts PassTickets in the Authorization header of the
HTTP requests using the basic authentication scheme. It is necessary to provide a service
APPLID in the apiml.authentication.applid parameter.
Tip: For more information, see Enabling PassTicket creation for API Services that accept
PassTickets.
safIdt
This value specifies that the application recognizes the SAF IDT scheme and fills the X-SAF-
Token header with the token produced by the Saf IDT provider implementation.

For more information, see SAF IDT provider

x509
This value specifies that a service accepts client certificates forwarded in the HTTP header.
The Gateway service extracts information from a valid client certificate. For validation, the
certificate needs to be trusted by API Mediation Layer, and needs to contain a Client
 Authentication (1.3.6.1.5.5.7.3.2) entry in Extended Key Usage. To use this scheme, it is also
necessary to specify which headers to include. Specify these parameters in headers .
zosmf
This value specifies that a service accepts z/OSMF LTPA (Lightweight Third-Party
Authentication). This scheme should only be used for a z/OSMF service used by the API
Gateway Authentication Service, and other z/OSMF services that are using the same LTPA key.
Tip: For more information about z/OSMF Single Sign-on, see Establishing a single sign-on
environment.
authentication.headers
When the x509 scheme is specified, use the headers parameter to select which values to
send to a service. Use one of the following values:
X-Certificate-Public

The public part of client certificate base64 encoded

X-Certificate-DistinguishedName

The distinguished name from client certificate

X-Certificate-CommonName

The common name from the client certificate

authentication.applid
This parameter specifies a service APPLID. This parameter is only valid for the
httpBasicPassTicket authentication scheme.

apiInfo
This section defines APIs that are provided by the service. Currently, only one API is supported.
apiInfo.apiId
that uses lowercase alphanumeric characters and a dot: . .
 apiInfo.gatewayUrl
This parameter specifies the base path at the API Gateway where the API is available. Ensure that
this path is the same as the gatewayUrl value in the routes sections.
apiInfo.swaggerUrl
(Optional) This parameter specifies the HTTP or HTTPS address where the Swagger JSON
document is available.
apiInfo.documentationUrl
(Optional) This parameter specifies a URL to a website where external documentation is provided.
This can be used when swaggerUrl is not provided.
apiInfo.version
(Optional) This parameter specifies the actual version of the API in semantic versioning format. This
can be used when swaggerUrl is not provided.
apiInfo.defaultApi
(Optional) This parameter specifics that the API is the default one to show in the API Catalog. If this
not set to true for any API, or multiple APIs have it set to true, then the default API becomes the API
with the highest major version as seen in apiInfo.version .
customMetadata
Custom metadata are described here.
catalogUiTileId
This parameter specifies the unique identifier for the API services group. This is the grouping value used
by the API Mediation Layer to group multiple API services together into "tiles". Each unique identifier
represents a single API Catalog UI dashboard tile. Specify the value based on the ID of the defined tile.
catalogUiTile
This section contains definitions of tiles. Each tile is defined in a section that has its tile ID as a key. A tile
can be used by multiple services.
 catalogUiTile.{tileId}.title
This parameter specifies the title of the API services product family. This value is displayed in the
API Catalog UI dashboard as the tile title.
catalogUiTile.{tileId}.description
This parameter specifies the detailed description of the API Catalog UI dashboard tile. This value is
displayed in the API Catalog UI dashboard as the tile description.
additionalServiceMetadata
This section contains a list of changes that allows adding or modifying metadata parameters for the
corresponding service.
additionalServiceMetadata.serviceId
This parameter specifies the service identifier for which metadata is updated.
additionalServiceMetadata.mode
This parameter specifies how the metadata are updated. The following modes are available:
UPDATE
Only missing parameters are added. Already existing parameters are ignored.
FORCE_UPDATE
All changes are applied. Existing parameters are overwritten.
additionalServiceMetadata.{updatedParameter}
This parameter specifies any metadata parameters that are updated.

Add and validate the definition in the API Mediation Layer

running on your machine
After you define the service in YAML format, you are ready to add your service definition to the API
Mediation Layer ecosystem.
The following procedure describes how to add your service to the API Mediation Layer on your local
machine.
Follow these steps:
. Copy or move your YAML file to the config/local/api-defs directory in the directory with API
Mediation Layer.
. Start the API Mediation Layer services.
Tip: For more information about how to run the API Mediation Layer locally, see Running the API
Mediation Layer on Local Machine.
. Run your Java application.
Tip: Wait for the services to be ready. This process may take a few minutes.
. Validate successful onboarding
You successfully defined your Java application if your service is running and you can access the service
endpoints. The following example is the service endpoint for the sample application:
https://localhost:10010/petstore/api/v2/pets/1

Add a definition in the API Mediation Layer in the Zowe

runtime
After you define and validate the service in YAML format, you are ready to add your service definition to the
API Mediation Layer running as part of the Zowe runtime installation on z/OS.
Follow these steps:
. Locate the Zowe instance directory. The Zowe instance directory is the directory from which Zowe was
launched, or else was passed as an argument to the SDSF command used to start Zowe. If you are
unsure which instance directory a particular Zowe job is using, open the JESJCL spool file and
navigate to the line that contains STARTING EXEC ZWESVSTC,INSTANCE= . This is the fully qualified
path to the instance directory.
Tip: For more information, see Creating and configuring the Zowe instance directory.
 Note: We use the ${zoweInstanceDir} symbol in following instructions.
. Add the fully qualified zFS path of your YAML file to ZWE_STATIC_DEFINITIONS_DIR in
zowe.yaml .

To hold your YAML file outside of the instance directory, add ZWE_STATIC_DEFINITIONS_DIR
variable to the zowe.environments section of zowe.yaml . Append the fully qualified zFS
path of the YAML file to the ZWE_STATIC_DEFINITIONS_DIR variable. You may specify multiple
zFS paths, separating each path by a semicolon.
To place your YAML file within the instance directory, copy your YAML file to the
${zoweInstanceDir}/workspace/api-mediation/api-defs directory.

Notes:
The ${zoweInstanceDir}/workspace/api-mediation/api-defs directory is created the
first time that Zowe starts. If you have not yet started Zowe, this directory might be missing.
The user ID ZWESVUSR that runs the Zowe started task must have permission to read the YAML
file.
. Ensure that your application that provides the endpoints described in the YAML file is running.
. Restart Zowe runtime or follow steps in section (Optional) Reload the services definition after the
update when the API Mediation Layer is already started which allows you to add your static API service
to an already running Zowe.
. Validate successful onboarding
You successfully defined your Java application if your service is running and you can access its endpoints.
The endpoint displayed for the sample application is:

(Optional) Check the log of the API Mediation Layer

The API Mediation Layer log can contain messages based on the API ML configuration. The API ML prints
the following messages to its log when the API definitions are processed:
Note: If these messages are not displayed in the log, ensure that the API ML debug mode is active.
(Optional) Reload the services definition after the update
when the API Mediation Layer is already started
The following procedure enables you to refresh the API definitions after you change the definitions when the
API Mediation Layer is already running.
Follow these steps:
. Use a REST API client to issue a POST request to the Discovery Service (port 10011):
http://localhost:10011/discovery/api/v1/staticApi

The Discovery Service requires authentication by a client certificate. If the API Mediation Layer is
running on your local machine, the certificate is stored at keystore/localhost/localhost.pem .
This example uses the HTTPie command-line HTTP client and is run with Python 3 installed:
Alternatively, it is possible to use curl to issue the POST call if it is installed on your system:
. Check if your updated definition is effective.
Note: It can take up to 30 seconds for the API Gateway to pick up the new routing.
Onboarding a REST API service with the
Version: v2.0.x LTS

YAML Wizard
As an API developer, you can use the Yaml Onboarding Wizard to simplify the process of onboarding new
REST API services to the Zowe API Mediation Layer. The wizard offers a walkthrough of the required steps to
create a correct configuration file which is used to set the application properties and Eureka metadata.

Onboarding your REST service with the Wizard

The following procedure describes how to onboard your REST service with the Wizard.
Follow these steps:
. In the dashboard of the API Catalog, click the Onboard New API dropdown located in the navbar.

. Choose the type of onboarding according to your preference (static or via enablers).

. (Optional) To prefill the fields, click Choose File to upload a complete or partial YAML file. The YAML file
is validated and the form fields are populated.

. Fill in the input fields according to your service specifications.

. Address each of the categories in the dialog dropdown.

. Click Save to apply your changes.

. Validate successful onboarding with the following step according to your onboarding method.
For static onboarding, the following validation message appears after successful onboarding:
 For onboarding using an enabler, click Copy to save the generated yaml file to your clipboard. Then
paste this yaml file in your project's service-configuration.yml file.

If you see your service in the list of API Catalog available services, you have onboarded your service
successfully.
Zowe API Mediation Layer Single-Sign-On
Version: v2.0.x LTS

Overview
You can extend Zowe and utilize Zowe Single-Sign-On (SSO) provided by Zowe API Mediation Layer (API
ML) to enhance system security and improve the user experience.
This article provides an overview of the API ML single-sign-on feature, the principle participants in the SSO
process, and links to detailed Zowe SSO documentation. Zowe Single-Sign-On is based on single-user
authentication which produces an access token that represents the user in communication with z/OS
services accessible through the API Mediation Layer. The access token is issued by the Zowe Authentication
and Authorization Service (ZAAS), which is part of API ML. ZAAS issues an access token based on valid
z/OS credentials. This token can be validated by any component participating in SSO.
Note: Currently, API ML can provide SSO only in a single security domain.
Zowe API ML client
API service accessed via Zowe API ML
Existing services that cannot be modified
The following diagram describes the interactions between the general participants in the single-sign-on
process.

There are two main types of components that participate in Zowe SSO through API ML:
Zowe API ML client
This type of component is user-facing and can obtain user credentials through a user interface
(web, CLI, desktop).
API ML clients can be confidential or public.
A Zowe API ML client calls API services through the API ML.
An example of such clients are Zowe CLI or Zowe Desktop.
An API service accessed through Zowe API ML
A service that is registered to API ML and is accessed through the API Gateway.
 Services are protected by an access token or PassTicket.
The access token or PassTicket can be validated by the called API service.
The following sections describe what is necessary to utilize SSO for both types of components.
Zowe API ML client
The Zowe API ML client needs to obtain an access token via the /login endpoint of ZAAS by
providing z/OS credentials.
A client can call the ZAAS /query endpoint to validate the token and get information from the token.
This is useful when the API client has the token but does not store the associated data such as the user
ID.
The API client needs to provide the access token to API services in the form of a Secure HttpOnly
cookie with the name apimlAuthenticationToken , or in the Authorization: Bearer HTTP
header as described in Authenticated Request.
API service accessed via Zowe API ML
This section describes the requirements that an API service needs to satisfy to adopt a Zowe SSO access
token.
The token received by the Gateway is first validated and then may be passed directly to the service.
Alternatively, the Gateway can exchange the token for a PassTicket if the API service is configured to
expect a PassTicket.
The API service can validate the token and extract information about the user ID by calling the ZAAS
/query endpoint.

The alternative is to validate the signature of the JWT token using the public key of the token issuer
(e.g. the API ML Gateway). The API service needs to have the API ML Gateway certificate along with the
full CA certification chain in the API service truststore.
Note: The REST API of ZAAS can easily be called from a Java application using the ZAAS Client.
Existing services that cannot be modified
If you have a service that cannot be changed to adopt the Zowe authentication token, the service can utilize
Zowe SSO if the API service is able to handle PassTickets.
Note: For more information, see Enabling PassTicket creation for API Services that Accept PassTickets for
more details.

Further resources
Authentication Methods
User guide for SSO in Zowe CLI
System requirements for using web tokens for SSO in Zlux and ZSS
Certificate configuration for the usage of web tokens for SSO in Zlux and ZSS
Obtaining Information about API Services
Version: v2.0.x LTS

As an API Mediation Layer user, information about API services can be obtained for various purposes. The
following list presents some of the use cases for using the API Mediation Layer:
To display available services based on a particular criterion (API ID, hostname, or custom metadata)
To locate a specific API service based on one or more specific criteria (for example the API ID)
To obtain information that permits routing through the API Gateway such as baseUrl or basePath
To obtain information about an API service, the service APIs, or instances of the service
This article provides further detail about each of these use cases.
API ID in the API Mediation Layer
Protection of Service Information
API Endpoints
Obtain Information about a Specific Service
Obtain Information about All Services
Obtain Information about All Services with a Specific API ID

API ID in the API Mediation Layer

The API ID uniquely identifies the API in the API ML. The API ID can be used to locate the same APIs that are
provided by different service instances. The API developer defines this ID.
For more information about baseUrl or basePath, see Components of URL.

Protection of Service Information

Information about API services is considered sensitive as it contains partial information about the internal
topology of the mainframe system. As such, this information should be made accessible only by authorized
users and services.
Access to this information requires authentication using mainframe credentials, and a SAF resource check is
done. The resource class and resource is defined in the ZWESECUR job. You can find more details about the
ZWESECUR job in Configuring the z/OS system for Zowe.
The security administrator needs to permit READ access to the APIML.SERVICES resource in the ZOWE
resource class to the your that can access the information about API services.
In IBM RACF, the access to the service information can be given by:
In Top Secret:
In ACF2:
API Gateway can be configured to check for SAF resource authorization in several ways. For details, see SAF
Resource Checking

API Endpoints
Obtain Information about a Specific Service
Use the following method to get information about a specific service:
GET /gateway/{serviceId}/api/v1/services

where:
{serviceId} is the service ID of the API service (Example: apicatalog )
This method returns a JSON response that describes the service. For more information, see Response
Format.
Obtain Information about All Services
Use the following method to get information about all services:
GET /gateway/api/v1/services

This method returns a JSON response with a list of all services. For more information, see Response Format.
Obtain Information about All Services with a Specific API ID
Use the following method to get information about all services with a specific API ID:
GET /gateway/api/v1/services?apiId={apiId}
where:
{apiId} is the API ID that represents required API (e.g. zowe.apiml.apicatalog )
This method returns a JSON response with a list of services provided by a specified API ID. For more
information, see Response Format.
Response Format
This section provides basic information about the structure of the response. The full reference on the field in
the response is presented in the API Catalog.
The apiml section provides information about the following points:
The service in the service subsection is displayed.
The APIs that are provided by the service in the apiInfo section. This section presents each major
API version that is provided by at least one instance. For each major version, the lowest minor version is
displayed.
The authentication methods that are supported by all instances are displayed.
API clients can use this information to locate the API based on API ID. baseUrl or basePath are used to
access the API through the API Gateway.
The instances section contains more details about the instances of the service. An API service can
provide more application specific details in customMetadata that can be used by API clients. Do not use
information in this section for use cases that API Gateway supports, such as routing or load balancing.
Example:
WebSocket support in API Gateway
Version: v2.0.x LTS

The API Gateway includes a basic WebSocket proxy which enables the Gateway to access applications that
use the WebSocket protocol together with a web UI and REST API.
The service can define what WebSocket services are exposed using Eureka metadata.
Example:
These metadata make it possible for requests from
wss://gatewayHost:port/serviceId/ws/v1/path to map to
ws://serviceHost:port/discoverableclient/ws/path , where:

serviceId
is the service ID of the service
path
is the remaining path segment in the URL.

Security and Authentication

The API Gateway usually uses TLS with the wss protocol. Services that use TLS enable the API Gateway to
use wss to access these services. Services that do not use TLS require the API Gateway to use the ws
protocol without TLS. The API Gateway also supports basic authentication via WebSocket.

Subprotocols
In addition to plain WebSocket support, API Mediation Layer also supports WebSocket subprotocols.
Currently, only STOMP v1.2 and STOMP v1.1 are supported and tested.
Note: It is possible to update the list of currently supported WebSocket subprotocols. Update the API
Gateway configuration using the environment variable SERVER_WEBSOCKET_SUPPORTEDPROTOCOLS with
the value of comma-separated subprotocol names. Support for additional subprotocols is not guaranteed as
these subprotocols are not being tested.
Example:
High availability
In the high availability scenario, the API Gateway makes it possible to open a new Websocket session by
utilizing the load balancing mechanism. Communication between the client and the server is handled by the
API Gateway by propagating the session to a live instance.

Diagnostics
The list of active routed WebSocket sessions is available at the Actuator endpoint websockets . On
localhost , it is available at https://localhost:10010/application/websockets.

Limitations
Different HTTP status code errors may result. The WebSocket session starts before the session between the
Gateway and the service starts. When a failure occurs when connecting to a service, the WebSocket session
terminates with a WebSocket close code and a description of the failure rather than an HTTP error code.
Create an Extension for API ML
Version: v2.0.x LTS

Zowe allows extenders to define their own extension for API ML. Follow the steps in this article to create your
extension and add it to the API Gateway classpath.
Note: The api-sample-extension-package contains a sample manifest.yml and the apiml-
sample-extension JAR that contains the extension.

Follow these steps:

. Create a JAR file from your extension. See the API ML sample extension to model the format of the JAR.
. Create a manifest.yml with the following structure. See the sample manifest.yml to model the
format of the yaml file.
For more information, see Packaging z/OS extensions.
Example:
The extension directory <instance>/workspace/gateway/sharedLibs/ is then added to the API
Gateway class path as part of the Zowe instance preparation.
Note: The paths defined under gatewaySharedLibs can either be a path to the directory where the
extensions JARs are located, or a path to the files.
Example:
After the JAR file and manifest.yml are customized according to your application, the extension is
extracted, scanned and added to the extension directory during the Zowe instance preparation. When the
API Gateway starts, the the API Gateway consumes the sample extension.
The extension should now be correctly added to the API Gateway classpath.

Call the REST endpoint for validation

Follow these steps to validate that you can call the REST endpoint defined in the controller via the API
Gateway:
. Call the https://<hostname>:<gatewayPort>/api/v1/greeting endpoint though Gateway.
. Verify that you receive the message, Hello, I'm a sample extension! as the response.
API Mediation Layer Message Service
Version: v2.0.x LTS

Component
The API ML Message Service component unifies and stores REST API error messages and log messages in a
single file. The Message Service component enables users to mitigate the problem of message definition
redundancy which helps to optimize the development process.
API Mediation Layer Message Service Component
Message Definition
Creating a message
Mapping a message
API ML Logger

Message Definition
API ML uses a customizable infrastructure to format both REST API error messages and log messages.
yaml files make it possible to centralize both API error messages and log messages. Messages have the
following definitions:
Message key - a unique ID in the form of a dot-delimited string that describes the reason for the
message. The key enables the UI or the console to show a meaningful and localized message.
Tips:
We recommend using the format org.zowe.sample.apiservice.{TYPE}.greeting.empty
to define the message key. {TYPE} can be the api or log keyword.
Use the message key and not the message number . The message number makes the code
less readable, and increases the possibility of errors when renumbering values inside the number .
Message number - a typical mainframe message ID (excluding the severity code)
Message type - There are two Massage types:
REST API error messages: ERROR
 Log messages: ERROR , WARNING , INFO , DEBUG , or TRACE
Message text - a description of the issue
Message reason - A reason for why this issue occured
Message action - What should I as a user do to correct the problem
The following example shows the message definition.
Example:

Creating a message
Use the following classes when you create a message:
org.zowe.apiml.message.core.MessageService - lets you create a message from a file.
org.zowe.apiml.message.yaml.YamlMessageService - implements
org.zowe.apiml.message.core.MessageService so that
org.zowe.apiml.message.yaml.YamlMessageService can read message information from a
yaml file, and create a message with message parameters.

Use the following process to create a message.

Follow these steps:
. Load messages from the yaml file.
Example:
. Use the Message createMessage(String key, Object... parameters); method to create a
message.
Example:

Mapping a message
You can map the Message either to a REST API response or to a log message.
When you map a REST API response, use the following methods:
mapToView - returns a UI model as a list of API Message, and can be used for Rest API error
messages
mapToApiMessage - returns a UI model as a single API Message

The following example is a result of using the mapToView method.

Example:
The following example is the result of using the mapToApiMessage method.
Example:
API ML Logger
The org.zowe.apiml.message.log.ApimLogger component controls messages through the
Message Service component.
The following example uses the log message definition in a yaml file.
Example:
When you map a log message, use mapToLogMessage to return a log message as text. The following
example is the output of the mapToLogMessage .
Example:
Use the ApimlLogger to log messages which are defined in the yaml file.
Example:
The following example shows the output of a successful ApimlLogger usage.
Example:
Zowe API Mediation Layer Security
Version: v2.0.x LTS

Zowe API Mediation Layer Security

How API ML transport security works
Transport layer security
Authentication
Zowe API ML services
Zowe API ML TLS requirements
Authentication for API ML services
Authentication endpoints
Supported authentication methods
Authentication with Username Password
Authentication with Client certificate
Authentication with JWT Token
Authentication parameters
Authentication providers
z/OSMF Authentication Provider
SAF Authentication Provider
Dummy Authentication Provider
Authorization
JWT Token
z/OSMF JSON Web Tokens Support
API ML truststore and keystore
API ML SAF Keyring
Discovery Service authentication
Setting ciphers for API ML services
ZAAS Client
Pre-requisites
API Documentation
Obtain a JWT token ( login )
Validate and get details from the token ( query )
Invalidate a JWT token ( logout )
 Obtain a PassTicket ( passTicket )
Getting Started (Step by Step Instructions)
Certificate management in Zowe API Mediation Layer
Running on localhost
How to start API ML on localhost with full HTTPS
Certificate management script
Generate certificates for localhost
Generate a certificate for a new service on localhost
Add a service with an existing certificate to API ML on localhost
Service registration to Discovery Service on localhost
Zowe runtime on z/OS
Import the local CA certificate to your browser
Generate a keystore and truststore for a new service on z/OS
Add a service with an existing certificate to API ML on z/OS
Procedure if the service is not trusted

How API ML transport security works

Security within the API Mediation Layer (API ML) is performed on several levels. This article describes how
API ML uses Transport Layer Security (TLS). As a system administrator or API developer, use this guide to
familiarize yourself with the following security concepts:
Transport layer security
The TLS protocol should be used to ensure secure data-transport for all connections to API Mediation Layer
services. While it is possible to disable the TLS protocol for debugging purposes or other use-cases, the
enabled TLS protocol is the default mode.
Authentication
Authentication is how an entity, whether it be a user (API Client), or an application (API Service), proves its
true identity.
API ML uses the following authentication methods:
User ID and password
 The user ID and password are used to retrieve authentication tokens
Requests originate from a user
The user ID and password are validated by a z/OS security manager whereby a token is issued that
is then used to access the API service
TLS client certificates
Certificates are used for service-only requests
Zowe API ML services
The following range of service types apply to the Zowe™ API ML:
Zowe API ML services
Gateway Service (GW) The Gateway is the access point for API clients that require access to API
services. API services can be accessed through the Gateway by API Clients. The Gateway receives
information about an API Service from the Discovery Service.
Discovery Service (DS) The Discovery Service collects information about API services and
provides this information to the Gateway and other services. API ML internal services also register
to the Discovery Service.
API Catalog (AC) The Catalog displays information about API services through a web UI. The
Catalog receives information about an API service from the Discovery Service.
Authentication and Authorization Service (AAS)
AAS provides authentication and authorization functionality to check user access to resources on z/OS.
The API ML uses z/OSMF API for authentication. For more information, see the API ML wiki
API Clients
API Clients are external applications, users, or other API services that access API services through the
API Gateway
API Services
API services are applications that are accessed through the API Gateway. API services register
themselves to the Discovery Service and can access other services through the Gateway. If an API
 service is installed so that direct access is possible, API services can access other services without the
Gateway. When APIs access other services, they can also function as API clients.
Zowe API ML TLS requirements
The API ML TLS requires servers to provide HTTPS ports. Each API ML service has the following specific
requirements:
API Client
The API Client is not a server
Requires trust of the API Gateway
Has a truststore or SAF keyring that contains certificates required to trust the Gateway
Gateway Service
Provides an HTTPS port
Has a keystore or SAF keyring with a server certificate
The certificate needs to be trusted by API Clients
This certificate should be trusted by web browsers because the API Gateway can be used to
display web UIs
Has a truststore or SAF keyring that contains certificates needed to trust API Services
API Catalog
Provides an HTTPS port
Has a keystore or SAF keyring with a server certificate
The certificate needs to be trusted by the API Gateway
This certificate does not need to be trusted by anyone else
Discovery Service
Provides an HTTPS port
Has a keystore or SAF keyring with a server certificate
Has a truststore or SAF keyring that contains certificates needed to trust API services
API Service
Provides an HTTPS port
 Has a keystore or SAF keyring with a server and client certificate
The server certificate needs to be trusted by the Gateway
The client certificate needs to be trusted by the Discovery Service
The client and server certificates can be the same
These certificates do not need to be trusted by anyone else
Has a truststore or SAF keyring that contains one or more certificates that are required to trust the
Gateway and Discovery Service
Authentication for API ML services
API Gateway
The API Gateway handles authentication
There are two authentication endpoints that allow authentication of the resource by providers
Diagnostic endpoints https://{gatewayUrl}:{gatewayPort}/application/** in API
Gateway are protected by basic authentication, Zowe JWT token, or a client certificate
API Catalog
API Catalog is accessed by users and requires a login
Protected access is performed by the Authentication and Authorization Service
Discovery Service
Discovery Service is accessed by API Services
This access (reading information and registration) requires protection by means of a client
certificate
(Optional) Access can be granted to users (administrators)
Diagnostic endpoints https://{gatewayUrl}:{gatewayPort}/application/** in
Discovery Service are protected by basic authentication, Zowe JWT token, or a client certificate
API Services
Authentication is service-dependent
It is recommended to use the Authentication and Authorization Service for authentication
Authentication endpoints
The API Gateway contains the following REST API authentication endpoints:
auth/login

The full path of the auth/login endpoint appears as https://{gatewayUrl} :

{gatewayPort}/gateway/api/v1/auth/login .

The auth/login endpoint authenticates mainframe user credentials and returns an authentication
token. The login request requires user credentials though one of the following methods:
Basic access authentication
JSON with user credentials
Client certificate
When authentication is successful, the response to the request is an empty body and a token is
contained in a secure HttpOnly cookie named apimlAuthenticationToken . When
authentication fails, the user receives a 401 status code.
auth/query

The full path of the auth/query endpoint appear as https://{gatewayUrl}:

{gatewayPort}/gateway/api/v1/auth/query .

The auth/query endpoint validates the token and retrieves the information associated with the
token. The query request requires the token through one of the following methods:
A cookie named apimlAuthenticationToken
Bearer authentication
When authentication is successful, the response to the request is a JSON object which contains
information associated with the token. When authentication fails, the user receives a 401 status
code.
auth/ticket

The auth/ticket endpoint generates a PassTicket for the user associated with a token. The full path
of the auth/ticket endpoint appears as https://{gatewayUrl}:
{gatewayPort}/gateway/api/v1/auth/ticket .

This endpoint is protected by a client certificate. The ticket request requires the token in one of the
following formats:
 Cookie named apimlAuthenticationToken .
Bearer authentication
The request takes the applicationName parameter, which is the name of the application for which
the PassTicket should be generated. Supply this parameter.
The response is a JSON object, which contains information associated with the ticket.
auth/refresh

Notes:
The endpoint is disabled by default. For more information, see Enable JWT token endpoint.
The endpoint is protected by a client certificate.
The auth/refresh endpoint generates a new token for the user based on valid jwt token. The full
path of the auth/refresh endpoint appears as https://{gatewayUrl}:
{gatewayPort}/gateway/api/v1/auth/refresh . The new token overwrites the old cookie with a
Set-Cookie header. As part of the process, the old token gets invalidated and is not usable anymore.

The refresh request requires the token in one of the following formats:
Cookie named apimlAuthenticationToken .
Bearer authentication
For more information, see the OpenAPI documentation of the API Mediation Layer in the API Catalog.
Supported authentication methods
The API Mediation Layer provides multiple methods which clients can use to authenticate. When the API ML
is run as part of Zowe, all of the following methods are enabled and supported. All methods are supported at
least to some extent with each authentication provider.
Authentication with Username/Password
The client can authenticate via Username and password. There are multiple methods which can be used to
deliver
credentials. For more details, see the ZAAS Client documentation.
Authentication with Client certificate
Beginning with release 1.19 LTS, it is possible to perform authentication with client certificates. This feature is
functional and tested, but automated testing on various security systems is not yet complete. As such, the
feature is provided as a beta release for early preview. If you would like to offer feedback using client
certificate authentication, please create an issue against the api-layer repository. Client Certificate
authentication will move out of Beta once test automation is fully implemented across different security
systems.
If the keyring or a truststore contains at least one valid certificate authority (CA) other than the CA of the API
ML, it is possible to use the client certificates issued by this CA to authenticate to the API ML. This feature is
not enabled by default and needs to be configured.
When providing credentials in any form together with client certificate on the same login request, the
credentials take precedence and client certificate is ignored.
Authentication is performed in the following ways:
The client calls the API ML Gateway login endpoint with the client certificate.
The client certificate and private key are checked as a valid TLS client certificate against the Gateway's
trusted CAs.
The public part of the provided client certificate is checked against SAF, and SAF subsequently returns
a user ID that owns this certificate. ZSS provides this API for the Mediation Layer.
The Gateway performs the login of the mapped user and returns a valid JWT token.

Prerequisites:
Alter the Zowe runtime user and set protection by password. The user is created with the
NOPASSWORD parameter by the Zowe installer. It is necessary to change this password. For RACF,
issue the following TSO command:
For other security systems, please refer to the documentation for an equivalent command.
Ensure that the Zowe runtime user is allowed to log in to z/OSMF (For example user is member of the
default IZUUSER group)
Ensure that you have an external Certificate Authority and signed client certificates, or generate these
certificates in SAF. The client certificate has to have correct Extended Key Usage metadata to allow
being used for TLS client authentication. ( OID: 1.3.6.1.5.5.7.3.2 )
 Import the client certificates to SAF, or add them to a user profile. (Examples: RACDCERT ADD or
RACDCERT GENCERT ). For more information, see your security system documentation.

Import the external CA to the truststore or keyring of the API Mediation Layer.
Configure Gateway for client certificate authentication.
To upgrade from Zowe 1.18 or lower, see the Additional security rights that need to be granted.
PassTicket generation must be enabled for the Zowe runtime user. The user has to be able to generate
PassTicket for itself and for the APPLID of z/OSMF. For more information, see Configure Passticket.
The Zowe runtime user has to be enabled to perform identity mapping in SAF. For more information, see
Additional security rights that need to be granted.
ZSS has to be configured to participate in Zowe SSO. For more information, see Using web tokens for
sso on Zlux and ZSS.
Authentication with JWT Token
When the client authenticates with the API ML, the client receives the JWT token in exchange. This token
can be used for further authentication. If z/OSMF is configured as the authentication provider and the client
already received a JWT token produced by z/OSMF, it is possible to reuse this token within API ML for
authentication.
Authentication parameters
Parameters are specified in the onboarding enablers.
Authentication parameters enable a service to accept a Zowe JWT or client certificate. The API Gateway
translates the authentication token to an authentication method supported by a service.
The following example shows the parameters that define the service authentication method:
Example:
authentication.scheme
The value of this parameter specifies a service authentication scheme. Any valid headers or X-Zowe-
Auth-Failure error headers are set and passed to southbound services. In addition, any X-Zowe-
Auth-Failure error headers coming from the northbound service are also be passed to the
southbound services without setting the valid headers. The X-Zowe-Auth-Failure error header
contains details about the error and suggests potential actions. The following schemes are supported
by the API Gateway:
bypass
This value specifies that the token is passed unchanged to service.
Note: This is the default scheme when no authentication parameters are specified.
zoweJwt
When a Zowe JWT is provided, this scheme value specifies that the service accepts the Zowe
JWT. No additional processing is done by the API Gateway.
When a client certificate is provided, the certificate is transformed into a Zowe JWT, and the
southbound service performs the authentication.
httpBasicPassTicket
This value specifies that a service accepts PassTickets in the Authorization header of the HTTP
requests using the basic authentication scheme. It is necessary to provide a service APPLID in the
authentication.applid parameter to prevent passticket generation errors.

When a JWT is provided, the service validates the Zowe JWT to use for passticket generation.
When a client certificate is provided, the service validates the certificate by mapping it to a
mainframe user to use for passticket generation.
For more information, see Enabling PassTicket creation for API Services that Accept PassTickets
zosmf
This value specifies that a service accepts z/OSMF LTPA (Lightweight Third-Party Authentication).
This scheme should only be used only for a z/OSMF service used by the API Gateway
Authentication Service and other z/OSMF services that use the same LTPA key.
When a JWT is provided, the token extracts the LTPA and forwards it to the service.
When a client certificate is provided, the certificate translates into a z/OSMF token, and also
extracts the LTPA for the service to use.
For more information about z/OSMF Single Sign-on, see Establishing a single sign-on environment
 safIdt
This value specifies that the service accepts SAF IDT, and expects that the token produced by the
SAF IDT provider implementation is in the X-SAF-Token header. It is necessary to provide a
service APPLID in the authentication.applid parameter.
For more information, see Implement a SAF IDT provider.
x509
This value specifies that a service accepts client certificates forwarded in the HTTP header. The
Gateway service extracts information from a valid client certificate. For validation, the certificate
needs to be trusted by API Mediation Layer, and needs to contain a Client Authentication
(1.3.6.1.5.5.7.3.2) entry in Extended Key Usage. To use this scheme, it is also necessary to specify
which headers to include. Specify these parameters in headers .
authentication.headers
When the x509 scheme is specified, use the headers parameter to select which values to send to a
service. Use one of the following values:
X-Certificate-Public

The public part of client certificate base64 encoded

X-Certificate-DistinguishedName

The distinguished name from client certificate

X-Certificate-CommonName

The common name from the client certificate

authentication.applid
This parameter specifies a service APPLID. This parameter is valid only for the
httpBasicPassTicket authentication scheme.

Authentication providers
API ML contains the following providers to handle authentication for the API Gateway:
 z/OSMF Authentication Provider

SAF Authentication Provider

Dummy Authentication Provider

z/OSMF Authentication Provider

The z/OSMF Authentication Provider allows the API Gateway to authenticate with the z/OSMF
service. The user needs z/OSMF access in order to authenticate.
Use the following properties of the API Gateway to enable the z/OSMF Authentication Provider :
SAF Authentication Provider
The SAF Authentication Provider allows the API Gateway to authenticate directly with the z/OS SAF
provider that is installed on the system. The user needs a SAF account to authenticate.
Use the following property of the API Gateway to enable the SAF Authentication Provider :
Note: To provide your own implementation of the SAF IDT provider, see the Implement new SAF provider
guidelines.
Dummy Authentication Provider
The Dummy Authentication Provider implements simple authentication for development purposes
using dummy credentials (username: user , password user ). The Dummy Authentication
Provider makes it possible for the API Gateway to run without authenticating with the z/OSMF service.

Use the following property of API Gateway to enable the Dummy Authentication Provider :
Authorization
Authorization is a method used to determine access rights of an entity.
In the API ML, authorization is performed by the z/OS security manager (ACF2, IBM RACF, Top Secret). An
authentication token is used as proof of valid authentication. The authorization checks, however, are always
performed by the z/OS security manager.
JWT Token
The JWT secret that signs the JWT Token is an asymmetric private key that is generated during Zowe
keystore configuration. The JWT token is signed with the RS256 signature algorithm.
You can find the JWT secret, alias localhost , in the PKCS12 keystore that is stored in
${KEYSTORE_DIRECTORY}/localhost/localhost.keystore.p12 . The public key necessary to
validate the JWT signature is read from the keystore.
You can also use the /gateway/api/v1/auth/keys/public/all endpoint to obtain all public keys that
can be used to verify JWT tokens signature in standard JWK format.
z/OSMF JSON Web Tokens Support
Your z/OSMF instance can be enabled to support JWT tokens as described at Enabling JSON Web Token
support. In this case, the Zowe API ML uses this JWT token and does not generate its own Zowe JWT token.
All authentication APIs, such as /gateway/api/v1/login and /gateway/api/v1/check function in
the same way as without z/OSMF JWT. Gateway service endpoint
/gateway/api/v1/auth/keys/public/all serves the z/OSMF JWK that can be used for JWT
signature validation.
API ML truststore and keystore
A keystore is a repository of security certificates consisting of either authorization certificates or public key
certificates with corresponding private keys (PK), used in TLS encryption. A keystore can be stored in Java
specific format (JKS) or use the standard format (PKCS12). The Zowe API ML uses PKCS12 to enable the
keystores to be used by other technologies in Zowe (Node.js).
API ML SAF Keyring
As an alternative to using a keystore and truststore, API ML can read certificates from a SAF keyring. The
user running the API ML must have rights to access the keyring. From the java perspective, the keyring
behaves as the JCERACFKS keystore. The path to the keyring is specified as
safkeyring:////user_id/key_ring_id . The content of SAF keyring is equivalent to the combined
contents of the keystore and the truststore.
Note: When using JCERACFKS as the keystore type, ensure that you define the class to handle the RACF
keyring using the -D options to specify the java.protocol.handler.pkgs property :
The elements in the following list, which apply to the API ML SAF Keyring, have these corresponding
characteristics:
The API ML local certificate authority (CA)
The API ML local CA contains a local CA certificate and a private key that needs to be securely stored.
The API ML local certificate authority is used to sign certificates of services.
The API ML local CA certificate is trusted by API services and clients.
The API ML keystore or API ML SAF Keyring
Server certificate of the Gateway (with PK). This can be signed by the local CA or an external CA.
Server certificate of the Discovery Service (with PK). This can be signed by the local CA.
Server certificate of the Catalog (with PK). This can be signed by the local CA.
The API ML keystore is used by API ML services.
The API ML truststore or API ML SAF Keyring
Local CA public certificate
External CA public certificate (optional)
Can contain self-signed certificates of API Services that are not signed by the local or external CA
Used by API ML services
Zowe core services
Services can use the same keystore and truststore or the same keyring as APIML for simpler installation
and management.
When using a keystore and truststore, services have to have rights to access and read them on the
filesystem.
When using a keyring, the user of the service must have authorization to read the keyring from the
security system.
Alternatively, services can have individual stores for higher security.
API service keystore or SAF keyring (for each service)
The API service keystore contains a server and client certificate signed by the local CA.
API service truststore or SAF keyring (for each service)
(Optional) The API service truststore contains a local CA and external CA certificates.
Client certificates
 A client certificate is a certificate that is used for validation of the HTTPS client. The client certificate of
a Discovery Service client can be the same certificate as the server certificate of the services which the
Discovery Service client uses.
Discovery Service authentication
There are several authentication mechanisms, depending on the desired endpoint, as described by the
following matrix:

Endpoint Authentication Note

method
UI (eureka basic auth(MF), see note about mainframe authentication
homepage) token

application/** basic auth(MF), see note about mainframe authentication

token
application/health, none
application/info
Allows for the other services to register without mainframe
credentials or token. API ML's certificate can be used. It is
stored in the
eureka/** client certificate keystore/localhost/localhost.keystore.p12
keystore or in the SAF keyring. It is exported to .pem format for
convenience. Any other certificate which is valid and trusted by
Discovery service can be used.
certificate,
discovery/** basic auth(MF), see note about mainframe authentication
token
Note: Some endpoints are protected by mainframe authentication. The authentication function is provided
by the API Gateway. This functionality is not available until the Gateway registers itself to the Discovery
Service.
Since the Discovery Service uses HTTPS, your client also requires verification of the validity of its certificate.
Verification is performed by validating the client certificate against certificates stored in the truststore or SAF
keyring.
Some utilities including HTTPie require the certificate to be in PEM format. The exported certificate in .pem
format is located here: keystore/localhost/localhost.pem .
The following example shows the HTTPie command to access the Discovery Service endpoint for listing
registered services and provides the client certificate:
Setting ciphers for API ML services
You can override ciphers that are used by the HTTPS servers in API ML services by configuring properties of
the Gateway, Discovery Service, and API Catalog.
Note: You do not need to rebuild JAR files when you override the default values in shell scripts.
The application.yml file contains the default value for each service, and can be found here. The default
configuration is packed in .jar files. On z/OS, you can override the default configuration in
<RUNTIME_DIR>/components/<APIML_COMPONENT>/bin/start.sh . Add the launch parameter of the
shell script to set a cipher:
On localhost, you can override the default configuration in config/local/gateway-service.yml (including other
YAML files for development purposes).
The following list shows the default ciphers. API ML services use the following cipher order:
Note: Ensure that the version of Java you use is compatible with the default cipherset.
Only IANA ciphers names are supported. For more information, see Cipher Suites or List of Ciphers.

ZAAS Client
The ZAAS client is a plain Java library that provides authentication through a simple unified interface without
the need for detailed knowledge of the REST API calls presented in this section. The Client function has only
a few dependencies including Apache HTTP Client, Lombok, and their associated dependencies. The client
contains methods to perform the following actions:
To obtain a JWT token
 To validate and get details from a JWT token
To invalidate the JWT token
To obtain a PassTicket
Pre-requisites
Java SDK version 1.8.
An active instance of the API ML Gateway Service.
A property file which defines the keystore or truststore certificates.
API Documentation
The plain java library provides the ZaasClient interface with following public methods:
This Java code enables your application to add the following functions:
Obtain a JWT token ( login )
Validate and get details from the token ( query )
Invalidate a JWT token ( logout )
Obtain a PassTicket ( passTicket )
Obtain a JWT token ( login )
To integrate login, call one of the following methods for login in the ZaasClient interface:
If the user provides credentials in the request body, call the following method from your API:
If the user provides credentials as Basic Auth, use the following method:
These methods return the JWT token as a String. This token can then be used to authenticate the user in
subsequent APIs.
Note: Both methods automatically use the truststore file to add a security layer, which requires configuration
in the ConfigProperties class.
Validate and get details from the token ( query )
Use the query method to get the details embedded in the token. These details include creation time of
the token, expiration time of the token, and the user who the token is issued to.
Call the query method from your API in the following format:
In return, you receive the ZaasToken Object in JSON format.
This method automatically uses the truststore file to add a security layer, which you configured in the
ConfigProperties class.

The query method is overloaded, so you can provide the HttpServletRequest object that contains
the token in the apimlAuthenticationToken cookie or in an Authorization header. You then receive the
ZaasToken Object in JSON format.

Invalidate a JWT token ( logout )

The logout method is used to invalidate the JWT token. The token must be provided in the Cookie header
and must follow the format accepted by the API ML.
Call the logout method from your API in the following format:
If the token is successfully invalidated, you receive a 204 HTTP status code in return.
Obtain a PassTicket ( passTicket )
The passTicket method has an added layer of protection. To use this method, call the method of the
interface, and provide a valid APPLID of the application and JWT token as input.
The APPLID is the name of the application (up to 8 characters) that is used by security products to
differentiate certain security operations (like PassTickets) between applications.
This method has an added layer of security, whereby you do not have to provide an input to the method
since you already initialized the ConfigProperties class. As such, this method automatically fetches the
truststore and keystore files as an input.
In return, this method provides a valid pass ticket as a String to the authorized user.
Tip: For additional information about PassTickets in API ML see Enabling PassTicket creation for API Services
that Accept PassTickets.
Getting Started (Step by Step Instructions)
To use this library, use the procedure described in this section.
Follow these steps:
. Add zaas-client as a dependency in your project.
You will need to specify the version of the zaas-client you want. zaas-client versioning
following the semantic versioning format of major.minor.patch . For example, 1.22.0 .
Gradle:
i. Create a gradle.properties file in the root of your project if one does not already exist.
ii. In the gradle.properties file, set the URL of the specific Artifactory containing the
SpringEnabler artifact.
iii. Add the following Gradle code block to the repositories section of your build.gradle file:
iv. Add the following Gradle dependency:
Maven:
i. Add the following XML tags within the newly created pom.xml file:
Tip: If you want to use snapshot version, replace libs-release with libs-snapshot in the repository
url and change snapshots->enabled to true.
ii. Then add the following Maven dependency:
. In your application, create your Java class which will be used to create an instance of ZaasClient ,
which enables you to use its method to login, query, and to issue a PassTicket.
. To use zaas-client , provide a property file for configuration.
Tip: Check org.zowe.apiml.zaasclient.config.ConfigProperites to see which properties
are required in the property file.
Configuration Properties:
Note: If httpOnly property is set to true, the ZAAS Client will access the API ML via HTTP protocol
without TLS. This meant for z/OS configuration with AT-TLS that will ensure that TLS and the required
client certificates are used.
 . Create an instance of ZaasClient in your class and provide the configProperties object.
Example:
You can now use any method from ZaasClient in your class.
Example:
For login, use the following code snippet:
The following codeblock is an example of a SampleZaasClientImplementation .
Example:

Certificate management in Zowe API Mediation Layer

Running on localhost
How to start API ML on localhost with full HTTPS
The https://github.com/zowe/api-layer repository already contains pre-generated certificates that can be
used to start API ML with HTTPS on your computer. The certificates are not trusted by your browser so you
can either ignore the security warning or generate your own certificates and add them to the truststore of
your browser or system.
The certificates are described in more detail in the TLS Certificates for localhost.
Note: When running on localhost, only the combination of using a keystore and truststore is supported.
Certificate management script
Zowe API Mediation Layer provides a script that can be used on Windows, Mac, Linux, and z/OS to generate
a certificate and keystore for the local CA, API Mediation Layer, and services.
This script is stored in zowe/zowe-install-packaging repository bin/apiml_cm.sh. It is a UNIX shell
script that can be executed by Bash or z/OS Shell. For Windows, install Bash by going to the following link:
cmder.
Generate certificates for localhost
Follow these steps:
. Clone the zowe-install-packaging repository to your local machine.
. Place the bin/apiml_cm.sh script intoto scripts directory in your API Mediation Layer repository
folder
. Use the following script in the root of the api-layer repository to generate certificates for localhost:
scripts/apiml_cm.sh --action setup

This script creates the certificates and keystore for the API Mediation Layer in your current workspace.
Generate a certificate for a new service on localhost
To generate a certificate for a new service on localhost, see Generating certificate for a new service on
localhost.
Add a service with an existing certificate to API ML on localhost
For more information about adding a service with an existing certificate to API ML on localhost, see Trust
certificates of other services.
Service registration to Discovery Service on localhost
To register a new service to the Discovery Service using HTTPS, provide a valid client certificate that is
trusted by the Discovery Service.
Zowe runtime on z/OS
Certificates for the API ML local CA and API ML service are managed by installing the Zowe runtime on z/OS.
Follow the instructions in Installing the Zowe runtime on z/OS.
There are two ways to set up certificates on a z/OS machine:
Certificates in SAF keyring
Certificates in UNIX files (keystore and truststore)
The Configuring Zowe certificates contains instructions about how to set up certificates during installation.
Follow the procedure in the applicable section described in this article during installation.
Import the local CA certificate to your browser
Trust in the API ML server is a necessary precondition for secure communication between Browser or API
Client application. Ensure this trust through the installation of a Certificate Authority (CA) public certificate.
By default, API ML creates a local CA. Import the CA public certificate to the truststore for REST API clients
and to your browser. You can also import the certificate to your root certificate store.
Notes:
If a SAF keyring is being used and set up with ZWEKRING JCL, the procedure to obtain the certificate
does not apply. It is recommended that you work with your security system administrator to obtain the
certificate. Start the procedure at step 2.
The public certificate in the PEM format is stored at
<KEYSTORE_DIRECTORY>/local_ca/localca.cer where <KEYSTORE_DIRECTORY> is defined
in a customized <RUNTIME_DIR>/bin/zowe-setup-certificates.env file during the installation
step that generates Zowe certificates. The certificate is stored in UTF-8 encoding so you need to
transfer it as a binary file. Since this is the certificate to be trusted by your browser, it is recommended
to use a secure connection for transfer.
Follow these steps:
. Download the local CA certificate to your computer. Use one of the following methods to download the
local CA certificate to your computer:
Use Zowe CLI (Recommended) Issue the following command:
zowe zos-files download uss-file --binary
$KEYSTORE_DIRECTORY/local_ca/localca.cer

Use sftp Issue the following command:

To verify that the file has been transferred correctly, open the file. The following heading and closing
should appear:
. Import the certificate to your root certificate store and trust it.
For Windows, run the following command:
certutil -enterprise -f -v -AddStore "Root" localca.cer
 Note: Ensure that you open the terminal as administrator. This will install the certificate to the
Trusted Root Certification Authorities.
For macOS, run the following command:
$ sudo security add-trusted-cert -d -r trustRoot -k
/Library/Keychains/System.keychain localca.cer

For Firefox, manually import your root certificate via the Firefox settings, or force Firefox to use the
Windows truststore.
Note: Firefox uses its own certificate truststore.
Create a new Javascript file firefox-windows-truststore.js at C:\Program Files
(x86)\Mozilla Firefox\defaults\pref with the following content:

Generate a keystore and truststore for a new service on z/OS

Note: This procedure applies to UNIX file keystore and truststore only. For the SAF keyring option, it is
recommended that you perform the actions manually using your security system commands.
You can generate a keystore and truststore for a new service by calling the apiml_cm.sh script in the
directory with API Mediation Layer:
Call the apiml_cm.sh script in the directory with the API Mediation Layer as in the following example.
Example:
where:
service-alias

is a unique string to identify the key entry. All keystore entries (key and trusted certificate entries) are
accessed via unique aliases. Since the keystore has only one certificate, you can omit this parameter
and use the default value localhost .
service-keystore

Specifies repository of security certificates plus corresponding private keys. The <keystore_path>
is the path excluding the extension to the keystore that is generated. It can be an absolute path or a
path relative to the current working directory. The key store is generated in PKCS12 format with the
.p12 extension. Ensure that the path is in an existing directory where your service expects the
keystore.
Example: /opt/myservice/keystore/service.keystore .
service-truststore

Contains certificates from other parties that you expect to communicate with, or from Certificate
Authorities that you trust to identify other parties. The <truststore_path> is the path excluding the
extension to the trust store that is generated. It can be an absolute path or a path relative to the current
working directory. The truststore is generated in PKCS12 format.
service-ext

Specifies the X.509 extension that should be the Subject Alternate Name (SAN). The SAN contains host
names that are used to access the service. You need to specify the same hostname that is used by the
service during API Mediation Layer registration.
Example: "SAN=dns:localhost.localdomain,dns:localhost,ip:127.0.0.1"
Note: For more information about SAN, see SAN or SubjectAlternativeName at Java Keytool - Common
Options.
service-dname

Specifies the X.509 Distinguished Name and is used to identify entities, such as those which are named
by the subject and issuer (signer) fields of X.509 certificates.
Example: "CN=Zowe Service, OU=API Mediation Layer, O=Zowe Sample, L=Prague,
S=Prague, C=CZ"

service-validity

Specifies the number of days until the certificate expires.

service-password

Specifies the keystore password. The purpose of the password is the integrity check. The access
protection for the keystore and keystore need to be achieved by making them accessible only by the
ZOVESVR user ID and the system administrator.
The local-ca-filename is the path to the keystore that is used to sign your new certificate with the
local CA private key. It should point to the $KEYSTORE_DIRECTORY/local_ca/localca where
$KEYSTORE_DIRECTORY is defined in a customized $ZOWE_ROOT_DIR/bin/zowe-setup-
certificates.env file during the installation step that generates Zowe certificates.

Add a service with an existing certificate to API ML on z/OS

Note: This procedure applies only to UNIX file keystore/truststore. For the SAF keyring option, we
recommend to perform the actions manually using your security system commands.
The API Mediation Layer requires validation of the certificate of each service that it accessed by the API
Mediation Layer. The API Mediation Layer requires validation of the full certificate chain. Use one of the
following methods:
Import the public certificate of the root CA that has signed the certificate of the service to the APIML
truststore.
Ensure that your service has its own certificate. If it was signed by intermediate CA, ensure that all
intermediate CA certificates are contained in the service's keystore.
Note: If the service does not provide an intermediate CA certificates to the API ML, then validation fails.
This can be circumvented by importing the intermediate CA certificates to the API ML truststore.
The following path is an example of importing a public certificate to the API ML truststore by calling in the
directory with API Mediation Layer.
Example:
Procedure if the service is not trusted
If your service is not trusted, you may receive a response with the HTTP status code 502 Bad Gateway and a
JSON response in the standardized format for error messages. The following request is an example of when
this errror response may occur.
Example:
http --verify=$KEYSTORE_DIRECTORY/local_ca/localca.cer GET https://<gatewayHost>:
<port>/<untrustedService>/api/v1/greeting

In this example, you receive a similar response:

The message has the key apiml.common.tlsError , and the message number AML0105 , and content
that explains details about the message.
If you receive this message, import the certificate of your service or the CA that signed it to the truststore of
the API Mediation Layer as described previously.
API Mediation Layer routing
Version: v2.0.x LTS

As an application developer, you can route your service through the Gateway using the API Mediation Layer
to consume a specific resource.
There are two ways to route your service to the API Mediation Layer:
Basic Routing (using Service ID and version)
Basic Routing (using only the service ID)

Terminology
Service
A service provides one or more APIs, and is identified by a service ID. Note that sometimes the term
"service name" is used to mean service ID.
The default service ID is provided by the service developer in the service configuration file.
A system administrator can replace the service ID with a deployment environment specific name using
additional configuration that is external to the service deployment unit. Most often, this is configured in
a JAR or WAR file.
Services are deployed using one or more service instances, which share the same service ID and
implementation.
URI (Uniform Resource Identifier)
A string of characters used to identify a resource. Each URI must point to a single corresponding
resource that does not require any additional information, such as HTTP headers.

APIML Basic Routing (using Service ID and version)

This method of basic routing is based on the service ID that identifies the service. The specific instance is
selected by the API Gateway. All instances require an identical response. Eureka and Zuul expect this type of
routing.
The URI identifies the resource, but does not identify the instance of the service as unique when multiple
instances of the same service are provided. For example, when a service is running in high-availability (HA)
mode.
Services of the same product that provide different resources, such as SYSVIEW on one system and
SYSVIEW in a different sysplex, cannot have the same service ID (the same URI cannot have two different
meanings).
In addition to the basic Zuul routing, the Zowe API Gateway supports versioning in which you can specify a
major version. The Gateway routes a request only to an instance that provides the specified major version of
the API.
The /api/ prefix is used for REST APIs. The prefix /ui/ applies to web UIs and the prefix /ws/
applies to WebSockets.
You can implement additional routing using a Zuul pre-filter. For more information about how to implement a
Zuul filter, see Router and Filter: Zuul
The URL format expected by the API Gateway is:
https://{gatewayHost}:{port}/{serviceId}/api/v{majorVersion}/{resource}

Example:
The following address shows the original URL of a resource exposed by a service:
The following address shows the API Gateway URL of the resource:
The following diagram illustrates how basic routing works:

Implementation Details
Service instances provide information about routing to the API Gateway via Eureka metadata.
Example:
In this example, the service has a service ID of helloworldservice that exposes the following
endpoints:
 UI - https://gateway/helloworldservice/ui/v1 routed to
https://hwServiceHost:port/helloworld/

API major version 1 - https://gateway/helloworldservice/api/v1 routed to

https://hwServiceHost:port/helloworld/v1

API major version 2 - https://gateway/helloworldservice/api/v2 routed to

https://hwServiceHost:port/helloworld/v2

where:
The gatewayUrl is matched against the prefix of the URL path used at the Gateway
https://gateway/urlPath , where urlPath is serviceId/prefix/resourcePath .

The service ID is used to find the service host and port.

The serviceUrl is used to prefix the resourcePath at the service host.
Note: The service ID is not included in the routing metadata, but the service ID is in the basic Eureka
metadata.

Basic Routing (using only the service ID)

This method of routing is similar to the previous method, but does not use the version part of the URL. This
approach is useful for services that handle versioning themselves with different granularity.
One example that only uses a service ID is z/OSMF.
Example:
z/OSMF URL through the Gateway: https://gateway:10010/zosmf/api/restjobs/jobs/...
where:
zosmf is the service ID.
/restjobs/1.0/... is the rest of the endpoint segment.

Note that no version is specified in this URL.

Enabling PassTicket creation for API Services
Version: v2.0.x LTS

that Accept PassTickets

As system programmer, you can configure Zowe to use PassTickets for API services that are compatible to
accept them to authenticate your service with the API Mediation Layer.

Overview
API clients can use either a Zowe JWT token or client certificate to access an API service even if the API
service itself does not support the JWT token or client certificate. The Zowe JWT token is available through
the API Gateway authentication endpoint.
When an API client provides a valid Zowe JWT token or client certificate to the API ML, the API Gateway then
generates a valid PassTicket for any API service that supports PassTickets. The API Gateway then uses the
PassTicket to access that API service. The API Gateway provides the user ID and password in the
Authorization header of the HTTP requests using the Basic authentication scheme.
Outline for enabling PassTicket support
Security configuration that allows the Zowe API Gateway to generate PassTickets for an API service
ACF2
Top Secret
RACF
API services that support PassTickets
API Services that register dynamically with API ML that provide authentication information
API Services that register dynamically with API ML but do not provide metadata
API services that are defined using a static YAML definition
Adding YAML configuration to API services that register dynamically with API ML

Outline for enabling PassTicket support

The following steps outline the procedure for enabling PassTicket Support:
. Follow the API service documentation that explains how to activate support for PassTickets.
The PassTickets for the API service must have the replay protection switched off. The PassTickets
are exchanged between Zowe API Gateway and the API Service in a secure mainframe
environment.
. Record the value of the APPLID of the API service.
. Enable the Zowe started task user ID to generate PassTickets for the API service.
. Enable PassTicket support in the API Gateway for your API service.
Note: PassTickets must be enabled for every user who requires access to the API service.

Security configuration that allows the Zowe API Gateway to

generate PassTickets for an API service
Consult with your security administrator to issue security commands to allow the Zowe started task user ID
to generate PassTickets for the API service.
Use the following variables to generate PassTickets for the API service to enable the Zowe started task user
ID:
<applid> is the APPLID value used by the API service for PassTicket support (e.g. OMVSAPPL )

<zowesrv> is Zowe started task user ID used during the Zowe installation

Replace the variables in the following examples with actual values.

ACF2
Grant the Zowe started task user ID permission to generate PassTickets for users of that API service. The
following code is an example of security commands that need to be issued.
Example:
Top Secret
Grant the Zowe started task user ID permission to generate PassTickets for users of that API service.
Example:
RACF
To enable PassTicket creation for API service users, define the profile IRRPTAUTH.<applid>.* in the
PTKTDATA class and set the universal access authority to NONE .

Grant the Zowe started task user ID permission to generate PassTickets for users of that API service.
Example:

API services that support PassTickets

The following types of API services support PassTickets:
API Services that register dynamically with API ML that provide authentication information
API Services that register dynamically with API ML but do not provide metadata
API services that are defined using a static YAML definition
API Services that register dynamically with API ML that provide authentication
information
API services that support Zowe API Mediation Layer and use dynamic registration to the Discovery Service
already provide metadata that enables PassTicket support.
As a system programmer, you are not required to do anything in this case. All required information is
provided by the API service automatically.
API Services that register dynamically with API ML but do not provide metadata
Some services can use PassTickets but the API ML does not recognize that the service can accept
PassTickets. For such services, you can provide additional service metadata externally in the same file that
contains the static YAML definiton. The static YAML definitions are described in REST APIs without code
changes required.
Add the following section to the YAML file with a static definition:
where:
<serviceId>
 is the service ID of the service to which you want to add metadata.
API services that are defined using a static YAML definition
Add the following metadata to the same level as the serviceId :
Example:
Note: The fields in this example are explained later in this article.

Adding YAML configuration to API services that register

dynamically with API ML
As a developer of an API service that registers dynamically with the API ML, you need to provide additional
metadata to tell the API Gateway to use PassTickets. Additional metadata tells the API Gateway how to
generate them. The following code shows an example of the YAML configuration that contains this
metadata.
Example:
where:
httpBasicPassTicket

is the value that indicates that the HTTP Basic authentication scheme is used with PassTickets.
<applid>

is the APPLID value that is used by the API service for PassTicket support (e.g. OMVSAPPL ).
Custom Metadata
Version: v2.0.x LTS

(Optional) Additional metadata can be added to the instance information that is registered in the Discovery
Service in the customMetadata section. This information is propagated from the Discovery Service to the
onboarded services (clients). In general, additional metadata do not change the behavior of the client. Some
specific metadata can configure the functionality of the API Mediation Layer. Such metadata are generally
prefixed with the apiml. qualifier. We recommend you define your own qualifier, and group all metadata
you wish to publish under this qualifier. If you use the Spring enabler, ensure that you include the prefix
apiml.service before the parameter name.

customMetadata.apiml.enableUrlEncodedCharacters
When this parameter is set to true , the Gateway allows encoded characters to be part of URL
requests redirected through the Gateway. The default setting of false is the recommended setting.
Change this setting to true only if you expect certain encoded characters in your application's
requests.
Important! When the expected encoded character is an encoded slash or backslash ( %2F , %5C ),
make sure the Gateway is also configured to allow encoded slashes. For more information, see Installing
the Zowe runtime on z/OS.
Note: If you use the Spring enabler, use the following parameter name:
apiml.service.customMetadata.apiml.enableUrlEncodedCharacters

customMetadata.apiml.connectTimeout
The value in milliseconds that specifies a period in which API ML should establish a single, non-
managed connection with this service. If omitted, the default value specified in the API ML Gateway
service configuration is used.
Note: If you use the Spring enabler, use the following parameter name:
apiml.service.customMetadata.apiml.connectTimeout

customMetadata.apiml.readTimeout
The value in milliseconds that specifies the time of inactivity between two packets in response from this
service to API ML. If omitted, the default value specified in the API MLGateway service configuration is
used.
Note: If you use the Spring enabler, use the following parameter name:
apiml.service.customMetadata.apiml.readTimeout

customMetadata.apiml.connectionManagerTimeout
HttpClient employs a special entity to manage access to HTTP connections called by the HTTP
connection manager. The purpose of an HTTP connection manager is to serve as a factory for new
HTTP connections, to manage the life cycle of persistent connections, and to synchronize access to
persistent connections. Internally, it works with managed connections which serve as proxies for real
connections. connectionManagerTimeout specifies a period in which managed connections with
API ML should be established. The value is in milliseconds. If omitted, the default value specified in the
API ML Gateway service configuration is used.
Note: If you use the Spring enabler, use the following parameter name:
apiml.service.customMetadata.apiml.connectionManagerTimeout

customMetadata.apiml.okToRetryOnAllOperations
Specifies whether all operations can be retried for this service. The default value is false . The
false value allows retries for only GET requests if a response code of 503 is returned. Setting this
value to true enables retry requests for all methods, which return a 503 response code. Enabling
retry can impact server resources resulting from buffering of the request body.
Note: If you use the Spring enabler, use the following parameter name:
apiml.service.customMetadata.apiml.okToRetryOnAllOperations

customMetadata.apiml.corsEnabled
When this parameter is set to true , CORS handling by the Gateway is enabled on the service level for
all service routes. For more information, refer to enabling CORS with Custom Metadata on the Gateway:
Advanced Gateway features configuration. Additional information can be found in this article about
Cross-Origin Resource Sharing (CORS).
Note: If you use the Spring enabler, use the following parameter name:
apiml.service.customMetadata.apiml.corsEnabled

customMetadata.apiml.gatewayAuthEndpoint
Specifies the Gateway authentication endpoint used by the ZAAS Client configuration. The default value
is /api/v1/gateway/auth . For more information about ZAAS Client, see ZAAS Client.
Note: If you use the Spring enabler, use the following parameter name:
apiml.service.customMetadata.apiml.gatewayAuthEndpoint

customMetadata.apiml.gatewayPort
Specifies the Gateway port used by the ZAAS Client configuration. The default value is 10010 . For
more information about ZAAS Client, see ZAAS Client.
Note: If you use the Spring enabler, use the following parameter name:
apiml.service.customMetadata.apiml.gatewayPort

customMetadata.apiml.corsAllowedOrigins
Optionally, service can specify which origins will be accepted by Gateway during the CORS handling.
When this parameter is not set, the accepted origins are * by default. You can provide a coma
separated list of values to explicitly limit the accepted origins.
Note: If you use the Spring enabler, use the following parameter name:
apiml.service.customMetadata.apiml.corsAllowedOrigins

For more information, refer to enabling CORS with Custom Metadata on the Gateway: Advanced
Gateway features configuration.
customMetadata.apiml.lb.type
This parameter is part of the load balancing configuration for the Deterministic Routing capability.
Through this parameter, the service can specify which load balancing schema the service requires. If
this parameter is not specified, the service is routed using the basic round robin schema. This
parameter can be set to the following values:
headerRequest

This value applies the Header Request load balancing schema. Clients can call the API Gateway
and provide a special header with the value of the requested instanceId. The Gateway understands
this as a request from the client for routing to a specific instance. Clients have several possibilities
for understanding the topology of service instances, such as via the /eureka/apps endpoint on
the Discovery service, or the /gateway/services endpoint on the Gateway. In either case, the
information is provided. The client can then request a specific instance by using the special header
described below.
The header name is X-InstanceId , and the sample value is discoverable-
client:discoverableclient:10012 . This is identical to instanceId property in the
registration of the Discovery service.
In combination with enabling Routed instance header, the client can achieve sticky session
functionality. (The term, 'sticky session' refers to the feature of many load balancing solutions to
route the requests for a particular session to the same physical machine that serviced the first
request for that session). The benefit of this approach is that there is no session on the Gateway,
and the client ultimately decides whether or not to go to a specific instance. This method uses the
following sequence:
a. The client calls API Gateway and gets routed to a service.
b. The client reads the X-InstanceId header value from the response to understand the
service was routed to.
c. For all subsequent requests, the client provides the X-InstanceId header with previously
read value to get routed to the same instance of the service.
authentication

This value applies the Authentication load balancing schema. This is a sticky session functionality
based on the ID of the user. The user ID is understood from the Zowe SSO token on the client's
request. Requests without the token are routed in a round robin fashion. The user is first routed in a
round robin fashion, and then the routed instance Id is cached. The instance information is used for
subsequent requests to route the client to the cached target service instance. This session's
default expiration time is 8 hours. After the session expires, the process initiates again.
In default configuration, this cache is stored on each Gateway instance. You can choose to
distribute this cache between the Gateway's instances. To do so, follow the steps described in
Distributed load balancer cache.
customMetadata.apiml.lb.cacheRecordExpirationTimeInHours
When the property customMetadata.apiml.lb.type is set to authentication , the user can
also define the expiration time for the selected instance information that is cached. This property aims
to prevent any discrepancy which might occur if the required target server is no longer available. The
default value is 8 hours.
customMetadata.apiml.response.compress
When this parameter is set to true , API ML compresses content for all responses from this services
using GZIP. API ML also adds the Content-Encoding header with value gzip to responses.
customMetadata.apiml.response.compressRoutes
When the customMetadata.apiml.response.compress parameter is set to true , this
parameter allows services to further limit the compressed routes. The parameter accepts ant style
routes deliminated by , . The expectation is to provide the absolute paths.
If relative paths are provided, the starting / is added. If the beginning of the pattern does not need to
be specifically defined, use **/{pathYouAreInterestedIn}
Examples:
/service/**

Compresses all paths starting with /service/

/service/api/v1/compress,/service/api/v1/custom-compress

Compresses the specific two routes

/\*\*/compress/\*\*

Compresses all paths that contain compress as a specific path

customMetadata.apiml.response.headers
(Optional) A service can specify headers that are added to the response by the Gateway. When this
parameter is not set or is empty, no headers are added. Header names and header values are separated
by : . Multiple headers can be added, delimited by , . If a header with the same name already exists
in the response, the Gateway overwrites the value of the header.
Examples:
Strict-Transport-Security:max-age=1234; includeSubDomains

Sets a header with name Strict-Transport-Security and value max-age=1234;

includeSubDomains .

Strict-Transport-Security:max-age=1234; includeSubDomains, X-Frame-

Options:SAMEORIGIN

Sets two headers:

1) Header with name Strict-Transport-Security and value max-age=1234;
includeSubDomains . 2) Header with name X-Frame-Options and value `SAMEORIGIN.

customMetadata.apiml.headersToIgnore
(Optional) A service can specify headers that are removed from the request to the southbound service
by the Gateway. When this parameter is not set or is empty, no headers are removed. Multiple headers
can be removed, delimited by , .
API Versioning
Version: v2.0.x LTS

Introduction
API Catalog is the catalog of published API services and their associated documentation that have been
discovered or might get available if provisioned from the service catalog.
Application program interface (API) is a set of functions and procedures that allow the creation of
applications which access the features or data of other applications, service, or systems.
Our API Catalog contains APIs of services provided by implementations of mainframe products. Service can
be implemented by one or more service instances (that provide exactly the same service for high-availability
or scalability).
Versioning
APIs are versioned. Users of the API specify the major version ( v1 , v2 ). Backward incompatible changes
can be introduced only with changing major version. The service can provide multiple versions of the API (it
should provide v{n} and previous v{n-1} versions).
REST
In our case, we are speaking about REST APIs, which is a way how to access and manipulate textual
representations of Web resources using uniform and a predefined set of stateless operations. Usually via
HTTP(S) protocol and using JSON format. Resources are identified by their Uniform Resource Identifier
(URIs). The services are accessed via APIML gateway. Example of a URI:
https://host:10010/endevormfno/api/v1/ENWSQA01/packages/PACKAGETST
(https://{gatewayHost}:{port}/{serviceName}/api/v{majorVersion}/{resource} ) See
Components of URL for more information about the URL components of REST APIs.

Data Model
The following data model describes the model behind data about APIs and API services in the API Catalog.
The most of the data are provided during service registration. In case of the dynamic registration they are
provided by the service. Some of them are determined by the service developer (API-related), system
administrator (service-related), and some of them can be altered by user (catalog tiles - in future).

(this a UML class diagram)

Catalog Tile - API Catalog UI groups API services into tiles. An API service can be in multiple tiles. The
purpose of titles is to organize API services on the dashboard of the API Catalog. Default catalog tiles are
constructed from the definitions provided by the services. In future, it will be possible for the user to modify
the tiles.
API - Api object represents a collection of specific versions of the same API which share the same apiId.
API Version represents a specific version of the API. This version can be documented by an external
documentation or by a Swagger document. This information is set by the developer of the API.
Swagger represents a Swagger specification instance for a specific API version. See
https://swagger.io/docs/specification/ for more details.
API Association provides information how a specific API version is provides by a specific service. Different
services can use different basePath. The full path to access endpoints is:
scheme://host:port/basePath/endpointPath . This information is set by the service developer.

Service represents a collection of all service instances. The description and title are taken from the service
with highest version, in case if this is not clear then the latest registered wins. API clients are using a service
and the API gateway chooses what service instance will be accessed. The same API version can be
implemented by multiple services. Such services are not interchangeable because they contain or access
different data.
Service instance is a real implementation of a service. It contains the information about where service is
running. The information are provided by the system programmer. The default title and description is
provided by service developer. Instances are interchangeable and they are used to achieve high availability.
Route - Routes provide a way how service URLs are mapped to the gateway. Gateway translates an URL
based on the start of the base path on the gateway and translates it to a base path that is used in the URL to
access the service. The purpose is to make possible to access services via the gateway with a consistent
URL format no matter what is the format at the service.
Version type follows semantic versioning (http://semver.org/) and is used on multiple places.
Service and instance
Service and instance are overloaded words that have a different meaning in different contexts. This
document uses similar meaning as in (Netflix) Eureka discovery service. Service (or application) is a logical
entity that is comprised of functionality to access and manipulate specific resources. Instances are real
processes (servers) that provide that functionality to clients. Eureka is used in distributed software world
where a service is implemented by many instances. But z/OSMF software services registry defines software
service instance and software service templates in the context of the provisioning where "instances" are
provisioned from "templates". z/OSMF service instance does not need to correspond exactly to Eureka
service. z/OSMF service instance does need to provide REST API. z/OSMF service instance can be anything
that can be provisioned (e.g. multiple services that provide REST API, one API service, additional instance for
a service, just a container for other services, a database server, a database, a table...).

API Versioning
Service instances provide one or more different API versions (we take only one assumption: one service
instance will not provide two versions with the same major version, no other assumptions which versions will
be provided and how - e.g. an instance can provide only one version and another version will be provided by
different instance, other services can have instances that provide multiple versions).
The API user specifies only the major version in the URI. The API catalog needs to differentiate between
different full versions internally and able to return a specific full version or return documentation for the
highest version of the specified major version that is supported by all running services.
Guidelines:
The version of the API, not dependent on the product release
Two last versions are supported
Major version - specified by the user of the API in the URI - increased only when backward incompatible
change is introduced (it is rare because the REST APIs should be designed to allow extensibility)
Minor version - not specified in the URI but the user should know what is it, important to display the
correct level of documentation. Increased when the API is extended with a new feature (if you use a new
resource available in v1.2, the service has to provide at least v1.2, the request fails on v1.1). If there are
multiple instances of the services that have different minor versions, the service together will say that
has the lowest minor version (e.g instance A provide v1.3 and v2.2, instance B was not yet upgraded
and provides v1.2 and v2.1, then the service provides v1.2 and v2.1)
Patch version - not specified in the URI, no difference in the API, used only when the API documentation
is patched or a bug was fixed, there is no change in the API
Implement a new SAF IDT provider
Version: v2.0.x LTS

As a Zowe API ML user, you can use the API Gateway to apply your own SAF Identity Token (IDT) provider by
implementing an existing interface.
How to create a SAF IDT provider
How to integrate your extension with API ML
How to use an existing SAF IDT provider
How to use the SAF IDT provider
To configure SAF IDT on z/OS, see Configure signed SAF Identity tokens (IDT).

How to create a SAF IDT provider

To create your own implementation of the SAF IDT provider, follow these steps:
. Implement the existing org.zowe.apiml.gateway.security.service.saf.SafIdtProvider
interface.
The SafIdtProvider interface contains the generate and verify methods. The generate
method can be overridden by your SAF IDT implementation to generate the SAF token on behalf of the
specified user. The verify method can be overridden to verify that the provided SAF token is valid.
. Register a bean in order to use the implemented SAF IDT provider.
Example:
You created a SAF IDT provider.

How to integrate your extension with API ML

To use your SAF IDT provider as an extension of API ML, see Create an extension for API ML.

How to use the SAF IDT provider

To use the newly created SAF IDT provider, it is necessary to set the parameter
apiml.authentication.scheme to safIdt in your service configuration. Your application then
properly recognizes the SAF IDT scheme and fills the X-SAF-Token header with the token produced by
your SAF IDT provider.

How to use an existing SAF IDT provider

You can generate and verify an existing SAF token by using an implementation of the SAF IDT provider that
utilizes a ZSS solution.
SafRestAuthenticationService is an example of the SAF IDT provider implementation which uses REST as a
method of communication.
To use SafRestAuthenticationService ensure that apiml.security.saf.provider is set to
rest . (This is the default value) Set the following environment parameters in zowe.yaml :

ZWE_configs_apiml_security_authorization_endpoint_url=https://${ZWE_haInstanc
e_hostname}:${GATEWAY_PORT}/zss/api/v1/saf/authenticate

ZWE_configs_apiml_security_authorization_endpoint_url=https://${ZWE_haInstanc
e_hostname}:${GATEWAY_PORT}/zss/api/v1/saf/verify

These ZSS endpoints are used by the SafRestAuthenticationService to generate and validate the
SAF token.

The following diagram illustrates how communication using the SAF IDT provider works:
Using the Caching Service
Version: v2.0.x LTS

As an API developer, you can use the Caching Service as a storage solution to enable resource sharing
between service instances, thereby ensuring High Availability of services. The Caching Service makes it
possible to store, retrieve, and delete data associated with keys. The Caching Service is designed to make
resource sharing possible for services that cannot be made stateless in two ways:
Using VSAM to store key/value pairs for production
Using InMemory
Note: In the current implementation of the Caching service, VSAM is required for the storage of key/value
pairs for production, as VSAM is a native z/OS solution for storing key/value pairs.
The Caching service is available only for internal Zowe applications, and is not exposed to the internet. The
Caching service supports a hot-reload scenario in which a client service requests all available service data.
Architecture
Storage methods
VSAM
Redis
Infinispan
InMemory
How to start the service
Methods to use the Caching service API
Configuration properties
Authentication

Architecture
A precondition to provide for High Availability of all components within Zowe is the requirement for these
components to be either stateless, or for the resources of the service to be offloaded to a location
accessible by all instances of the service. This condition also applies to recently started instances. Some
services, however, are not, and cannot be stateless. The Caching Service is designed for these types of
services.
REST APIs make it possible to create, delete, and update key-value pairs in the cache. Other APIs read a
specific key-value pair or all key-value pairs in the cache.
Information from cached APIs is stored as a JSON in the following format:

Storage methods
The Caching Service supports the following storage solutions, which provide the option to add custom
implementation.
VSAM
VSAM can be used to organize records into four types of data sets: key-sequenced, entry-sequenced,
linear, or relative record. Use VSAM as the storage solution for production. VSAM is used primarily for
applications and is not used for source programs, JCL, or executable modules. ISPF cannot be used to
display or edit VSAM files.
For more information about the VSAM storage access method, see Using VSAM as a storage solution
through the Caching service.
Redis
Redis is a common storage solution that runs outside of the z/OS platform. It can store data structures in
key-value pairs, has high-availability support, and is highly performant.
For more information about the Redis storage access method, see Using Redis as a storage solution through
the Caching service.
Infinispan
Infinispan is a storage solution that can also run on the z/OS platform. It can store data structures in key-
value pairs, has high-availability support, and is highly performant.
For more information about the Infinispan storage access method, see Using Infinispan as a storage solution
through the Caching service.
InMemory
TODO (add in memory procedure) The InMemory storage method is a method suitable for testing and
integration verification. Be sure not to use InMemory storage in production. The key/value pairs are stored
only in the memory of a single instance of the service. As such, the key/value pairs do not persist.

How to start the service

By default, the Caching service starts along with the other Zowe components. To prevent the Caching
service from starting, set components.caching-service.enabled to false in zowe.yaml .

Methods to use the Caching service API

To apply a method to the Caching service, use the following API path:
/cachingservice/api/v1/cache/${path-params-as-needed}

Use the following methods with the Caching Service API:

POST /cache

Creates a new key in the Cache

GET /cache

Returns all key/value pairs for specific service

PUT /cache/{key}

Updates the existing value for the given key

GET /cache/{key}

Returns the existing value for the given key

DELETE /cache/{key}

Deletes a key/value pair

Configuration properties
The Caching Service uses the standard application.yml structure for configuration. The service is built
on top of the Spring enabler. As such, it dynamically registers to the API Mediation Layer. The service
appears in the API Catalog under the tile, "Zowe Applications".
caching.storage.size

This property limits the size of the Caching Service. In the VSAM and InMemory implementations, this
property represents the number of records stored before the eviction strategy is initiated. The default
value is 100 .
Note: Different implementations may implement this property differently.
caching.storage.evictionStrategy

This parameter specifies service behavior when the limit of records is reached. The default value is
Reject .

where:
reject
rejects the new item with the HTTP status code 507 when the service reaches the configured
maximum number
removeOldest
removes the oldest item in the cache when the service reaches the configured maximum number
Notes:
For more information about how to configure the Caching Service in the application.yml , see: Add
API Onboarding Configuration.
When using VSAM, ensure that you set the additional configuration parameters. For more information
about setting these parameters, see Using VSAM as a storage solution through the Caching service.

Authentication
Direct calls
Caching service requires TLS mutual authentication. This verifies authenticity of client. Calls without valid
client certificate generate 403 response code: Forbidden. This requirement is disabled when
VERIFY_CERTIFICATES=false in zowe-certificates.env configuration file.

Call must have a header X-Certificate-DistinguishedName containing information about

certificate's distinguished name. This header is added by API Gateway. It needs to be added manually for
direct call. Calls without this header produce 401 response code: Unauthorized.
Routed calls through API Gateway
Caching service registers with the following authentication scheme to Discovery service:
which makes Gateway to attempt mutual authentication with Client and if succesfull, propagate the Client's
certificate information to X-Certificate- headers. With this scheme, Gateway will use it's server/client
certificate for the routed call to caching service.
Using VSAM as a storage solution through
Version: v2.0.x LTS

the Caching service

As an API developer, you can configure VSAM as a storage solution through the Caching service. The
procedure in this article describes how to configure your storage solution for VSAM. Configuring VSAM
ensures that you do not lose data if you need to restart. Configuring VSAM also makes it possible to leverage
multiple caching services concurrently, whereby clients can retreive data through VSAM.
Understanding VSAM
VSAM configuration
VSAM performance

Understanding VSAM
Virtual Storage Access Method (VSAM) is both a data set type, and a method for accessing
various user data types. Using VSAM as an access method makes it possible to maintain disk records in a
unique format that is not understandable by other access methods. VSAM is used primarily for applications,
and is not used for source programs, JCL, or executable modules. ISPF cannot be used to display or edit
VSAM files. VSAM can be used to organize records into four types of data sets: key-sequenced, entry-
sequenced, linear, or relative record. The API Caching service supports VSAM as a storage method to cache
APIs, and uses the Key Sequence Data Set (KSDS) dataset. Each record has one or more key fields,
and a record can be retrieved (or inserted) by the key value, thereby providing random access to data.
Records are of variable length. IMS™ uses KDSDs.
For more information about VSAM, see the IBM documentation.
VSAM configuration
Configure VSAM as a storage solution through the Caching service by modifying the following configuration
parameters in zowe.components.caching-service in zowe.yaml .
storage.vsam.name

The ZFile filename. The ZFile is a wrapper around a z/OS file based on the supplied name and options.
This method calls the fopen() and fldata() C-library routines. The ZFile filename should follow the
 specific naming convention //'DATASET.NAME' .
storage.vsam.keyLength

The VsamKey length. The default value is 128 bytes.

storage.vsam.recordLength

The record length. The default value is 4096 bytes.

storage.vsam.encoding

The character encoding. The default value is IBM-1047.

VSAM performance
Accessing VSAM via java results in a performance limitation. The VSAM solution has been tested in a few
scenarios.
The following sequence describes the test process:
. Load 1000 records into the cache concurrently (5 threads).
. Update all records for 120 seconds with increasing the thread count, up to <x> amount of threads.
. Read all records for 120 seconds with increasing the thread count, up to <x> amount of threads.
. Read and update all records for 120 seconds with increasing the thread count, up to <x> amount of
threads.
. Delete all loaded records from the cache concurrently (5 threads).
Tests were run with 3 scenarios:
Low load: 5 threads
Medium load: 15 threads
High load: 50 threads
Test subjects:
Single Caching Service with VSAM storage
Two Caching Services with shared VSAM storage
Results:
The most important operation is READ .
Two Caching Services achieve better READ performance than a single Caching Service.
Based on data from the testing results, the READ performance appears to be acceptable, ranging from
300 ms to 1000 ms.
With two Caching Services and a high load, READ performance significantly increased.
Response times of other operations are also acceptable, yet error rates increase with higher
concurrency.
Two Caching Services produce higher load on shared resource (VSAM) and have higher error rate.
VSAM implemetation appears to be sufficient for user-based workloads. For light automation workloads
VSAM implementation appears to be acceptable as well. For heavy workloads this implementatin may
not be sufficient.
VSAM does not scale well beyond 1000 RPM on a node.
Using Redis as a storage solution through the
Version: v2.0.x LTS

Caching service
As an API developer, you can configure Redis as a storage solution through the Caching service. This article
describes how to configure your storage solution for Redis. You can configure Redis for high availability as
well as to replicate data to provide data durability and availability.
Understanding Redis
Redis configuration

Understanding Redis
Redis is an off-Z storage solution that stores data structures in key-value pairs. The API Caching service
uses hash sets, where each service storing data via the Caching service has its own hash, and each data
entry is a key-value entry within that service's Redis hash set.
For more information on Redis, see the official Redis documentation.
Redis replica instances
Redis can be used with one standalone instance. For data durability, however, a master/replica configuration
is recommended. Redis replicas automatically connect, and re-connect when necessary, to the master Redis
instance and attempt to be an exact copy of the master.
For more information on Redis replication and how to configure a replica instance, see the official Redis
Replication documentation.
Redis Sentinel
Redis Sentinel is a configuration that provides high availability for Redis master/replica instances. Sentinel
instances are used to monitor the master instance and use a quorum to automatically determine if a failover
procedure needs to occur from a master instance to one of its replicas.
For more information on Redis Sentinel and how to configure Sentinel instances with master/replica
instances, see the official Redis Sentinel documentation.
Redis SSL/TLS
Redis supports SSL/TLS starting in version 6. For information on enabled SSL/TLS with Redis, see the official
Redis TLS Support documentation.
Redis and Lettuce
The Lettuce library is used to connect to Redis. Lettuce uses Master or Sentinel node registration
information to automatically discover other instances. The IP address used to register between nodes is
therefore what Lettuce uses to connect to downstream replica instances. This means the IP address of
replica instances, or the IP address of both master and replica instances in the case of Sentinel topology,
must be accessible to the Caching service. For example, in a master/replica topology running in separate
Docker containers, the replica container's IP address needs to be accessible to the Caching service, rather
than only exposing a port.

Redis configuration
Configure Redis as a storage solution through the Caching service by setting the following environment
variables. Environment variables can be set by adding them to the zowe.components.caching-
service section of the zowe.yaml configuration file.

storage.redis.masterNodeUri

The URI used to connect to the Redis master instance in the form username:password@host:port .
The host section of the URI is mandatory
The port section is optional and if not included defaults to 6379 .
The username section is optional and if not included defaults to the Redis default username
default .

The password section is optional, but must be included if a username is included. If the password is
not set a username cannot be set.
storage.redis.timeout

The timeout duration in seconds for the Caching service when first connecting to Redis. Defaults to 60
seconds.
storage.redis.sentinel.masterInstance
The Redis master instance ID used by the Redis Sentinel instances. Required if Redis Sentinel is being
used.
storage.redix.sentinel.nodes

The URI used to connect to a Redis Sentinel instance in the form username:password@host:port .
The host section of the URI is mandatory
The port section is optional and if not included defaults to 6379 .
The password section is optional and defaults to no password.
To supply multiple Redis Sentinel URIs, concatenate the URIs with a comma , .
storage.redix.ssl.enabled

A flag indicating if Redis is being used with SSL/TLS support. Defaults to true .
storage.redis.ssl.keystore

The keystore file used to store the private key. Defaults to the Caching Service's keystore.
storage.redis.ssl.keystorePassword

The password used to unlock the keystore. Defaults to the Caching Service's keystore password.
storage.redis.ssl.truststore

The truststore file used to keep other parties public keys and certificates. Defaults to the Caching
Service's truststore.
storage.redix.ssl.truststorePassword

The password used to unlock the truststore. Defaults to the Caching Service's truststore password.
Overview
Version: v2.0.x LTS

You can create application plug-ins to extend the capabilities of the Zowe™ Application Framework. An
application plug-in is an installable set of files that present resources in a web-based user interface, as a set
of RESTful services, or in a web-based user interface and as a set of RESTful services.
Read the following topics to get started with extending the Zowe Application Framework.

How Zowe Application Framework works

Read the following topics to learn how Zowe Application Framework works:
Creating application plug-ins
Plug-ins definition and structure
Dataservices
Zowe Desktop and window management
Configuration Dataservice
URI Broker
Application-to-application communication
Error reporting UI
Logging utility

Tutorials
The following tutorials are available in Github.
Stand up a local version of the Example Zowe Application Server
GITHUB REPO:
zlux-app-server
User Browser Workshop App
 GITHUB REPO:
User Browser Workshop App
Internationalization in Angular Templates in Zowe Application Server
GITHUB SAMPLE REPO:
sample-angular-app (Internationalization)
App to app communication
GITHUB SAMPLE REPO :
sample-angular-app (App to app communication)
Using the Widgets Library
GITHUB SAMPLE REPO:
sample-angular-app (Widgets)
Configuring user preferences (configuration dataservice)
GITHUB SAMPLE REPO:
sample-angular-app (configuration dataservice)

Samples
Zowe allows extensions to be written in any UI framework through the use of an Iframe, or Angular and React
natively. In this section, code samples of various use-cases will be provided with install instructions.
TROUBLESHOOTING SUGGESTIONS:
If you are running into issues, try these suggestions:
 Restart the Zowe Server/ VM.
Double check that the name in the plugins folder matches your identifier in
pluginsDefinition.json located in the Zowe root.

After logging into the Zowe desktop, use the Chrome or Firefox developer tools and navigate to the
"network" tab to see what errors you are getting.
Check each file with cat <filename> to be sure it wasn't corrupted while uploading. If files
were corrupted, try uploading using a different method like SCP or SFTP.

Sample Iframe App

GITHUB SAMPLE REPO:
sample-iframe-app

Sample Angular App

GITHUB SAMPLE REPO:
sample-angular-app

Sample React App

GITHUB SAMPLE REPO:
sample-react-app

User Browser Workshop Starter App

GITHUB SAMPLE REPO:
workshop-starter-app
This sample is included as the first part of a tutorial detailing communication between separate Zowe apps.
It should be installed on your system before starting the User Browser Workshop App Tutorial
The App's scenario is that it has been opened to submit a task report to a set of users who can handle the
task. In this case, it is a bug report. We want to find engineers who can fix this bug, but this App does not
contain a directory listing for engineers in the company, so we need to communicate with some App that
does provide this information. In this tutorial, you must build an App which is called by this App in order to list
engineers, is able to be filtered by the office that they work from, and is able to submit a list of engineers
which would be able to handle the task.
After installing this app on your system, follow directions in the User Browser Workshop App Tutorial to
enable app-to-app communication.
Plug-ins definition and structure
Version: v2.0.x LTS

The Zowe™ Application Server ( zlux-app-server ) enables extensiblity with application Plugins.
Application Plugins are a subcategory of the unit of extensibility in the server called a plugin.
The files that define a Plugin are located in the pluginsDir directory.

pluginDefinition.json
This file describes an application Plugin to the Zowe Application Server. (A Plugin is the unit of extensibility
for the Zowe Application Server. An application Plugin is a Plugin of the type "Application", the most common
and visible type of Plugin.) A definition file informs the server whether the application Plugin has server-side
dataservices, client-side web content, or both. The attributes of this file are defined within the
pluginDefinition json-schema document

Application Plugin filesystem structure

An application Plugin can be loaded from a filesystem that is accessible to the Zowe Application Server, or it
can be loaded dynamically at runtime. When accessed from a filesystem, there are important considerations
for the developer and the user as to where to place the files for proper build, packaging, and operation.
Root files and directories
The root of an application Plugin directory contains the pluginDefinition.json file, and the following other files
and directories.
Dev and source content
Aside from demonstration or open source application Plugins, the following directories should not be visible
on a deployed server because the directories are used to build content and are not read by the server.
nodeServer
When an application Plugin has router-type dataservices, they are interpreted by the Zowe Application
Server by attaching them as ExpressJS routers. It is recommended that you write application Plugins using
Typescript, because it facilitates well-structured code. Use of Typescript results in build steps because the
pre-transpilation Typescript content is not to be consumed by NodeJS. Therefore, keep server-side source
code in the nodeServer directory. At runtime, the server loads router dataservices from the lib directory.
webClient
When an application Plugin has the webContent attribute in its definition, the server serves static content for
a client. To optimize loading of the application Plugin to the user, use Typescript to write the application
Plugin and then package it using Webpack. Use of Typescript and Webpack result in build steps because
the pre-transpilation Typescript and the pre-webpack content are not to be consumed by the browser.
Therefore, separate the source code from the served content by placing source code in the webClient
directory.
Runtime content
At runtime, the following set of directories are used by the server and client.
lib
The lib directory is where router-type dataservices are loaded by use in the Zowe Application Server. If
the JS files that are loaded from the lib directory require NodeJS modules, which are not provided by the
server base (the modules zlux-server-framework requires are added to NODE_PATH at runtime),
then you must include these modules in lib/node_modules for local directory lookup or ensure that they
are found on the NODE_PATH environment variable. nodeServer/node_modules is not automatically
accessed at runtime because it is a dev and build directory.
web
The web directory is where the server serves static content for an application Plugin that includes the
webContent attribute in its definition. Typically, this directory contains the output of a webpack build.
Anything you place in this directory can be accessed by a client, so only include content that is intended to
be consumed by clients.
Packaging applications as compressed files
Application Plugin files can be served to browsers as compressed files in brotli (.br) or gzip (.gz) format. The
file must be below the application's /web directory, and the browser must support the compression
method. If there are multiple compressed files in the /web directory, the Zowe Application Server and
browser perform runtime negotiation to decide which file to use.
Default user configuration
Configuration Dataservice default settings for users can be packaged within a Plugin.
This is done by putting content within the /config/storageDefaults folder, and more on that subject
can be found here
App-to-App Communication
App-to-App communication behaviors can be statically defined or dynamically created at runtime. Static
definitions help as a form of documentation and to be able to depend upon them, so it is recommended that
these be packaged with a Plugin if you wish other's to be able to use App-to-App communication on your
App.
This page describes the subject in more detail.
In summary, App-to-App Actions and Recognizers can be stored within an App's /config/actions and
/config/recognizers folders, respectively, where the filenames much match the identifiers of Apps.

Documentation
In order for Zowe servers to pick up documentation to present to UIs, they must be in a uniform place.
The /doc folder of any Plugin can contain at its root any READMEs or documents that an administrator or
developer may care about when working with a Plugin for the first time.
The /doc/swagger folder on the other hand, will be used to store .yaml extension Swagger 2.0 files that
document the APIs of a Plugin's dataservices if they exist.
Other folders may exist, such as /doc/ui to document help behavior that may be shown in a UI, but is not
implemented at this time.

Location of Plugin files

The files that define a Plugin are located in the plugins directory.
pluginsDir directory
At startup, the server reads from the plugins directory. The server loads the valid Plugins that are found
by the information that is provided in the JSON files.
Within the pluginsDir directory are a collection of JSON files. Each file has two attributes, which serve to
locate a Plugin on disk:
location: This is a directory path that is relative to the server's executable (such as zlux-app-
server/bin/start.sh ) at which a pluginDefinition.json file is expected to be found.

identifier: The unique string (commonly styled as a Java resource) of a Plugin, which must match what is in
the pluginDefinition.json file.

Application Dataservices
See Dataservices

Application Configuration Data

The App server has a component for managing an App's configuration & user data, organized by scope
such as user, group, and server instance. For more information, see Configuration Dataservice
Documentation.
Building plugin apps
Version: v2.0.x LTS

You can build a plugin app by using the following steps as a model. Alternatively, you can follow the Sample
Angular App tutorial.
Plugins can have any build process desired as long as it doesn't conflict with the packaging structure. The
basic requirement for a plugin app is that static web content must be in a /web directory, and server and
other backend files must be in a /lib directory.
Before you can build a plugin app you must install all prerequisites.

Building web content

. On the computer where the virtual desktop is installed, use the the following command to specify a
value for the MVD_DESKTOP_DIR environment variable:
Where <path> is the install location of the virtual desktop.
. Navigate to /<plugin_dir>/webClient . If there is no /webClient directory, proceed to the
Building server content section below.
. Run the npm install command to install any application dependencies. Check for successful return
code.
. Run one of the following commands to build the application code:
Run the npm run build command to generate static content in the /web directory. (You can
ignore warnings as long as the build is successful.)
Run the npm run start command to compile in real-time. Until you stop the script, it compiles
code changes as you make them.

Building app server content

. Navigate to the plugin directory. If there is no /nodeServer directory in the plugin directory, proceed
to the Building Javascript content (*.js files) section below.
 . Run the npm install command to install any application dependencies. Check for successful return
code.
. Run one of the following commands to build the application code:
Run the npm run build command to generate static content in the /lib directory.
Run the npm run start command to compile in real-time. Until you stop the script, it compiles
code changes as you make them.

Building zss server content

. Clone the zss repository and its submodule zowe-common-c.
. Make a build script that compiles your C code with -Wc,dll and -Wl,dll, and other flags as seen in this
zowe example
. Include a ZSS .x file to link zss server APIs to your plugin, as seen in this zowe example
. Ensure that the build output ends up in the /lib folder as a .so file that has the z/OS program control
( +p ) extended attribute.

Tagging plugin files on z/OS

When Zowe App Framework is installed on z/OS developers should tag their plugin files according to the file
content. Tagging files helps programs on z/OS understand how to interpret those files, most importantly to
know whether a file is encoded using EBCDIC (Extended Binary Coded Decimal Interchange Code). If you
are unsure if a plugin you are using is tagged, it can be checked and set using the chtag command. If you
want to set the tags, it can be done in bulk with the help of these programs:
Autotag: This free, open-source application is not part of Zowe. You can download the binary from here
for example https://anaconda.org/izoda/autotag. Source: https://github.com/RocketSoftware/autotag
The Zowe tagging script: This script tags by file extension. It might not work for all cases, but can be
altered to suit your needs. Source: https://github.com/zowe/zowe-install-
packaging/blob/master/scripts/tag-files.sh

Building Javascript content (*.js files)

Unlike Typescript, Javascript is an interpreted language and does not need to be built. In most cases,
reloading the page should build new code changes. For Iframes or other JS-based apps, close and open the
app.

Installing
Follow the steps described in Installing plugins to add your built plugin to the Zowe desktop.

Packaging
For more information on how to package your Zowe app, developers can see Plugins definition and
structure.
Installing Plugins
Version: v2.0.x LTS

Plugins can be added or removed from the Zowe App Server, as well as upgraded. There are two ways to do
these actions: By REST API or by filesystem. The instructions below assume you have administrative
permissions either to access the correct REST APIs or to have the necessary permissions to update server
directories & files.
NOTE: Plugins must be pre-built, and follow the directory structure, and have all dependencies met
to be successfully installed. Read the appServer or install-app log files within the Zowe instance's
<logDirectory> directory, (ex ~/.zowe/log/install-app.log ) if a plugin does not show in the
Zowe desktop, but has been installed successfully.

By filesystem
The App server uses directories of JSON files, described in the server configuration document. Defaults are
located in the folder zlux-app-server/defaults/plugins , but the server reads the list of plugins
instead from the instance directory, at <workspaceDirectory>/app-server/plugins (for example,
~/.zowe/workspace/app-server/plugins which includes JSON files describing where to find a
plugin. Adding or removing JSONs from this folder will add or remove plugins upon server restart, or you can
use REST APIs and cluster mode to add or remove plugins without restarting).
Adding/Installing
Plugins must be packaged as Components. You can install a plugin by running the component installer, zwe
components install . For more information, try the help command zwe components install --
help .

Removing
Plugins are hidden from the Desktop when a component is disabled. If a component is removed, the plugins
from the component will be removed too.
Upgrading
Currently, only one version of a plugin can exist per server. So, to upgrade, you either upgrade the plugin
within its pre-existing directory by rebuilding it (with more up to date code), or you alter the locator JSON of
that app to point to the content of the upgraded version.
Modifying without server restart (Exercise to the reader)
The server's reading of the locator JSONs and initializing of plugins only happens during bootstrapping at
startup. However, in cluster mode the bootstrapping happens once per worker process. Therefore, it is
possible to manage plugins without a server restart by killing & respawning all worker processes without
killing the cluster master process. This is what the REST API does, internally. To do this without the REST
API, it may be possible to script knowing the parent process ID, and running a kill command on all child
processes of the App server cluster process.

By REST API
The server REST APIs allow plugin management without restarting the server - you can add, remove, and
upgrade plugins in real-time. However, removal or upgrade must be done carefully as it can disrupt users of
those plugins.
This swagger file documents the REST API for plugin management
The API only works when RBAC is configured, and an RBAC-compatible security plugin is being used. An
example of this is zss-auth, and use of RBAC is described in this documentation and in the wiki.
NOTE: If you do not see your plugin in the Zowe desktop check the appServer and install-app log files within
the Zowe instance's <logDirectory> directory to troubleshoot the problem. If you are building your own
desktop extension then you need to pre-build your plugin with the correct directory structure, and meet all
dependencies.
Plugin management during development
Below are some tasks developers can do to work with plugins. These should not be done in production, as
plugins are managed automatically at the component level.
Installing
When running the app-server without zowe server infrastructure and tooling, it's still possible to install
plugins directly. To add or install a plugin, run the script zlux-app-server/bin/install-app.sh
providing the location to a plugin folder. For example:
./install-app.sh /home/john/zowe/sample-angular-app

This will generate a JSON file <workspaceDirectory>/app-

server/plugins/org.zowe.zlux.sample.angular.json that contains the plugin's ID and its location
on disk. These JSON files tell the Desktop where to find apps and are the glue between the Zowe instance's
desktop and the plugin code itself held in its directory.
. For example, if we were to install the sample angular-app in the folder /home/john/zowe/sample-
angular-app , then the JSON would be:

Removing
To remove a plugin, locate the server's instance plugin directory <workspaceDirectory>/app-
server/plugins (for example, ~/.zowe/workspace/app-server/plugins ) and remove the locator
JSON that is associated with that plugin. Remove the plugin's content by deleting it from the file system if
applicable.
Embedding plugins
Version: v2.0.x LTS

Add these imports to a component where you want to embed another plugin:
Inject Angular2PluginEmbedActions into your component constructor:
In the component template prepare a container where you want to embed the plugin:
In the component class add a reference to the container:
In the component class add a reference to the embedded instance:
Everything is ready to start embedding, you just need to know the pluginId that you want to embed:

How to interact with embedded plugin

If the main component of embedded plugin declares Input and Output properties then you can interact with
it. ApplicationManager provides methods to set Input properties and get Output properties of the embedded
plugin. Suppose, that the embedded plugin declares Input and Output properties like this:
Obtain a reference to ApplicationManager in your component constructor:
Note: We are unable to inject ApplicationManager with @Inject() until an AoT-compiler issue with
namespaces is resolved: angular/angular#15613
Now you can set sampleInput property, obtain sampleOutput property and subscribe to it:

How to destroy embedded plugin

There is no special API to destroy embedded plugin. If you want to destroy the embedded plugin just clear
the container for the embedded plugin and set embeddedInstance to null:

How to style a container for the embedded plugin

It is hard to give a universal recipe for a container style. At least, the container needs position:
"relative" because the embedded plugin may have absolutely positioned elements. Here is sample
styles you can start with if your component utilizes flexbox layout:

Applications that use embedding

Workflow app demonstrates advanced usage.
Dataservices
Version: v2.0.x LTS

Dataservices are dynamic backend components of Zowe™ plug-in applications. You can optionally add them
to your applications to make the application do more than receive static content from the proxy server. Each
dataservice defines a URL space that the server can use to run extensible code from the application.
Dataservices are mainly intended to create REST APIs and WebSocket channels.

Defining dataservices
You define dataservices in the application's pluginDefinition.json file. Each application requires a
definition file to specify how the server registers and uses the application's backend. You can see an
example of a pluginDefinition.json file in the top directory of the sample-angular-app.
In the definition file is a top level attribute called dataServices , for example:
To define your dataservice, create a set of keys and values for your dataservice in the dataservices
array.

Schema
The documentation on dataservice types and parameters for each are specified within the
pluginDefinition.json json-schema document

Defining Java dataservices

In addition to other types of dataservice, you can use Java (also called java-war) dataservices in your
applications. Java dataservices are powered by Java Servlets.
To use a Java dataservice you must meet the prerequisites, define the dataservice in your plug-in definition,
and define the Java Application Server library to the Zowe Application Server.
Prerequisites
Install a Java Application Server library. In this release, Tomcat is the only supported library.
 Make sure your plug-in's compiled Java program is in the application's /lib directory, in either a
.war archive file or a directory extracted from a .war archive file. Extracting your file is
recommended for faster start-up time.
Defining Java dataservices
To define the dataservice in the pluginDefinition.json file, specify the type as java-war , for
example:
To access the service at runtime, the plug-in can use the Zowe dataservice URL standard:
/ZLUX/plugins/[PLUGINID]/services/[SERVICENAME]/[VERSIONNUMBER]

Using the example above, a request to get users might be:

/ZLUX/plugins/[PLUGINID]/services/javaservlet/1.0.0/users

Note: If you extracted your servlet contents from a .war file to a directory, the directory must have the
same name as the file would have had. Using the example above, javaservlet.war must be extracted
to a directory named \javaservlet .
Defining Java Application Server libraries
In the zlux-app-server/zluxserver.json file, use the example below to specify Java Application
Server library parameters:
Specify the following parameters in the languages.java object:
runtimes (object) - The name and location of a Java runtime that can be used by one or more
services. Used to load a Tomcat instance.
name (object) - The name of the runtime.
home (string) - The path to the runtime root. Must include /bin and /lib directories.

ports (array <number> )(Optional) - An array of port numbers that can be used by instances of Java
Application Servers or microservices. Must contain as many ports as distinct servers that will be
spawned, which is defined by other configuration values within languages.java . Either ports or
portRange is required, but portRange has a higher priority.

portRange (array <number> )(Optional) - An array of length 2, which contains a start number and
end number to define a range of ports to be used by instances of application servers or microservices.
You will need as many ports as distinct servers that will be spawned, which is defined by other
 configuration values within languages.java . Either ports or portRange is required, but
portRange has a higher priority.

war (object) - Defines how the Zowe Application Server should handle java-war dataservices.
defaultGrouping (string)(Optional) - Defines how services should be grouped into instances of
Java Application Servers. Valid values: appserver or microservice . Default: appserver .
appserver means 1 server instance for all services. microservice means one server
instance per service.
pluginGrouping (array <object> )(Optional) - Defines groups of plug-ins to have their java-
war services put within a single Java Application Server instance.
plugins (Array <string> ) - Lists the plugins by identifier which should be put into this
group. Plug-ins with no java-war services are skipped. Being in a group excludes a plugin
from being handled by defaultGrouping .
runtime (string)(Optional) - States the runtime to be used by the Tomcat server instance, as
defined in languages.java.runtimes .
javaAppServer (object) - Java Application Server properties.
type (string) - Type of server. In this release, tomcat is the only valid value.
path (string) - Path of the server root, relative to zlux-app-server/lib . Must include
/bin and /lib directories.

config (string) - Path of the server configuration file, relative to zlux-app-server/lib .

https (object) - HTTPS parameters.
key (string) - Path of a private key, relative to zlux-app-server/lib .
certificate (string) - Path of an HTTPS certificate, relative to zlux-app-server/lib .
Java dataservice logging
The Zowe Application Server creates the Java Application Server instances required for the java-war
dataservices, so it logs the stdout and stderr streams for those processes in its log file. Java Application
Server logging is not managed by Zowe at this time.
Java dataservice limitations
Using Java dataservices with a Zowe Application Server installed on a Windows computer, the source and
Java dataservice code must be located on the same storage volume.
To create multiple instances of Tomcat on non-Windows computers, the Zowe Application Server
establishes symbolic links to the service logic. On Windows computers, symbolic links require administrative
privilege, so the server establishes junctions instead. Junctions only work when the source and destination
reside on the same volume.

Using dataservices with RBAC

If your administrator configures the Zowe Application Framework to use role-based access control (RBAC),
then when you create a dataservice you must consider the length of its paths.
To control access to dataservices, administrators can enable RBAC, then use a z/OS security product such
as RACF to map roles and authorities to a System Authorization Facility (SAF) profile. For information on
RBAC, see Applying role-based access control to dataservices.
SAF profiles have the following format:
<product>.<instance id>.SVC.<pluginid_with_underscores>.<service>.<HTTP method>.
<dataservice path with forward slashes '/' replaced by periods '.'>

For example, to access this dataservice endpoint:

/ZLUX/plugins/org.zowe.foo/services/baz/_current/users/fred

Users must have READ access to the following profile:

ZLUX.DEFAULT.SVC.ORG_ZOWE_FOO.BAZ.POST.USERS.FRED

Profiles cannot contain more than 246 characters. If the path section of an endpoint URL makes the profile
name exceed limit, the path is trimmed to only include elements that do not exceed the limit. For example,
imagine that each path section in this endpoint URL contains 64 characters:
/ZLUX/plugins/org.zowe.zossystem.subsystems/services/data/_current/aa..a/bb..b/cc
..c/dd..d

So aa..a is 64 "a" characters, bb..b is 64 "b" characters, and so on. The URL could then map to the
following example profile:
ZLUX.DEFAULT.SVC.ORG_ZOWE_ZOSSYSTEM_SUBSYSTEMS.DATA.GET.AA..A.BB..B

The profile ends at the BB..B section because adding CC..C would put it over 246 characters. So in this
example, all dataservice endpoints with paths that start with AA..A.BB..B are controlled by this one
profile.
To avoid this issue, we recommend that you maintain relatively short endpoint URL paths.

Dataservice APIs
Dataservice APIs can be categorized as Router-based or ZSS-based, and either WebSocket or not.
Router-based dataservices
Each Router dataservice can safely import Express, express-ws, and bluebird without requiring the modules
to be present, because these modules exist in the proxy server's directory and the NODE_MODULES
environment variable can include this directory.
HTTP/REST Router dataservices
Router-based dataservices must return a (bluebird) Promise that resolves to an ExpressJS router upon
success. For more information, see the ExpressJS guide on use of Router middleware: Using Router
Middleware.
Because of the nature of Router middleware, the dataservice need only specify URLs that stem from a root
'/' path, as the paths specified in the router are later prepended with the unique URL space of the
dataservice.
The Promise for the Router can be within a Factory export function, as mentioned in the
pluginDefinition specification for routerFactory above, or by the module constructor.

An example is available in the Sample Angular App.

WebSocket Router dataservices
ExpressJS routers are fairly flexible, so the contract to create the Router for WebSockets is not significantly
different.
Here, the express-ws package is used, which adds WebSockets through the ws package to ExpressJS. The
two changes between a WebSocket-based router and a normal router are that the method is 'ws', as in
router.ws(<url>,<callback>) , and the callback provides the WebSocket on which you must define
event listeners.
See the ws and express-ws topics on www.npmjs.com for more information about how they work, as the API
for WebSocket router dataservices is primarily provided in these packages.
An example is available in zlux-server-framework/plugins/terminal-
proxy/lib/terminalProxy.js

Router dataservice context

Every router-based dataservice is provided with a Context object upon creation that provides definitions
of its surroundings and the functions that are helpful. The following items are present in the Context
object:
serviceDefinition
The dataservice definition, originally from the pluginDefinition.json file within a plug-in.
serviceConfiguration
An object that contains the contents of configuration files, if present.
logger
An instance of a Zowe Logger, which has its component name as the unique name of the dataservice within
a plug-in.
makeSublogger
A function to create a Zowe Logger with a new name, which is appended to the unique name of the
dataservice.
addBodyParseMiddleware
A function that provides common body parsers for HTTP bodies, such as JSON and plaintext.
plugin
An object that contains more context from the plug-in scope, including:
pluginDef: The contents of the pluginDefinition.json file that contains this dataservice.
server: An object that contains information about the server's configuration such as:
 app: Information about the product, which includes the productCode (for example: ZLUX ).
user: Configuration information of the server, such as the port on which it is listening.
Router storage API
ZSS based dataservices
ZSS dataservices much like zlux router services can be used to implement REST or websocket APIs. Each
service is associated with a URL which when requested will call a function to handle the request or
websocket message event.
HTTP/REST ZSS dataservices
ZSS REST dataservices are registered into ZSS with a service installer function, where initializerName
is the function name located in the dll libraryName . The methods list what HTTP methods are
expected of this dataservice. Example:
The service installer is given DataService , which includes context such as the above definition plus a
loggingIdentifier . The service is also given HttpServer , a reference to ZSS and its configuration.
To register the dataservice, you must make an HttpService object like
Then you must assign properties to the dataservice, such as
authType: What type of authentication and authorization checks should be done before calling this
service. values such as SERVICE_AUTH_NONE when the service does not need securty or
SERVICE_AUTH_NATIVE_WITH_SESSION_TOKEN when the service should be protected by ZSS's
cookie are valid.
serviceFunction: The function within this dataservice that will be called whenever a request is received.
runInSubtask: (TRUE/FALSE) Whether to run the service function in a subtask or not whenever a
request is received.
doImpersonation: (TRUE/FALSE) When true, the service function will be ran as the authenticated user,
rather than the server user. This is recommended whenever possible to keep permissions management
in line with the users own permissions.
Example of service installer:
When a request is received, the service function is called with the HttpService and HttpResponse
objects. HttpService is used to store and retrieve cached data and access the storage API.
HttpRequest is a pointer within the response object, and utilities exist to help with parsing it.
Example of request handling:
ZSS dataservice context and structs
Headers to important dataservice structs include
HttpResponse
HttpRequest
HttpService
HttpServer
Json handling
DataService context
Utilities
Data structures
ZSS storage API
The DataService struct contains two Storage structs, localStorage and remoteStorage . They
implement the same API for getting, setting, and removing data, but manage the data in different locations.
localStorage stores data within the ZSS server, for high speed access. remoteStorage stores data
in the Caching Service, for high availability state storage.
Usage example: Sample angular app storage test api: https://github.com/zowe/sample-angular-
app/blob/v1.23.0-RC1/zssServer/src/storage.c

Documenting dataservices
It is recommended that you document your RESTful application dataservices in OpenAPI (Swagger)
specification documents. The Zowe Application Server hosts Swagger files for users to view at runtime.
To document a dataservice, take the following steps:
. Create a .yaml or .json file that describes the dataservice in valid Swagger 2.0 format. Zowe
validates the file at runtime.
 . Name the file with the same name as the dataservice. Optionally, you can include the dataservice
version number in the format: <name>_<number> . For example, a Swagger file for a dataservice
named user must be named either users.yaml or users_1.1.0.yaml .
. Place the Swagger file in the /doc/swagger directory below your application plug-in directory, for
example:
/sample-angular-app/doc/swagger/hello.yaml

At runtime, the Zowe Application Server does the following:

Dynamically substitutes known values in the files, such as the hostname and whether the endpoint is
accessible using HTTP or HTTPS.
Builds documentation for each dataservice and for each application plug-in, in the following locations:
Dataservice documentation:
/ZLUX/plugins/<app_name>/catalogs/swagger/servicename

Application plug-in documentation: /ZLUX/plugins/<app_name>/catalogs/swagger

In application plug-in documentation, displays only stubs for undocumented dataservices, stating that
the dataservice exists but showing no details. Undocumented dataservices include non-REST
dataservices such as WebSocket services.
Authentication API
Version: v2.0.x LTS

This topic describes the web service API for user authentication.
The authentication mechanism of the ZLUX server allows for an administrator to gate access to services by
a given auth handler, while on the user side the authentication structure allows for a user to login to one or
more endpoints at once provided they share the same credentials given.

Handlers
The auth handlers are a type of zlux server plugin (type=nodeAuthentication) which are categorized by
which kind of authentication they can provide. Whether it's to z/OS via type=saf or theoretical
authentication such as Facebook or Amazon cloud, the handler API is abstract to handle different types of
security needs.
Handler installation
Auth handler plugins are installed like any other plugin.
Handler configuration
The server top-level configuration attribute dataserviceAuthentication states properties about
which plugins to use and how to use them.
For example,
The dataserviceAuthentication attribute has the following properties:
defaultAuthentication: Which authentication category to choose by default, in case multiple are
installed.
rbac: Whether or not the server should do authority checks in addition to authentication checks when
requesting a dataservice.
Handler context
These plugins are given an object, context , in the constructor. Context has attributes to help the plugin
know about the server configuration, provide a named logger, and more. The parameters include:
pluginDefinition: The object describing the plugin's definition file
pluginConf: An object that gives the plugin its configuration from the Config Service internal storage
serverConfiguration: The object describing the server's current configuration
context: An object holding contextual objects
logger: A logger with the name of the plugin's ID
Handler capabilities
A handler's constructor should return a capabilities object that states which capabilities the plugin has. If a
capabilities object is not returned, it is assumed that only the authenticate and authorize functions are
implemented, for backward compatibility support. The capabilities object should include:
canGetCategories: (true/false) If the getCategories() function exists, which returns a string array of
categories of auth the plugin can support given the server context. This is useful if the plugin can
support multiple categories conditionally.
canLogout: (true/false) If the logout(request, sessionState) function exists. Used to clear state and
cookies when a session should be ended.
canGetStatus: (true/false) If the getStatus(sessionState) function exists
canRefresh: (true/false) If the refreshStatus(request, sessionState) function exists, which is used to
renew a session that has an expiration limit.
canAuthenticate: (true/false) If the authenticate(request, sessionState):Promise function exists
(Required, assumed)
canAuthorized: (true/false) If the *authorized(request, sessionState, options) function exists (Required,
assumed)
haCompatible: (true/false) Used to be sure that a plugin has no state that would be lost in a high
availibility environment.
canGenerateHaSessionId: (true/false) If generateHaSessionId(request) exists, which is used to set the
value used for an app-server session for a user. When not in a high availability environment, the app-
server generates its own session ID.
canResetPassword: (true/false) If passwordRest(request, sessionState) exists
proxyAuthorizations: (true/false) If the addProxyAuthorizations(req1, req2Options, sessionState)
function exists
Examples
sso-auth, which conditionally implements the saf, zss, and apiml security types:
https://github.com/zowe/zlux-server-framework/tree/v2.x/master/plugins/sso-auth
High availability (HA)
Some auth handlers are not capable of working in a high availability environment. In these environments,
there can be multiple zlux servers and there may not be a safe and secure way to share session state data.
This extends to the zlux server cookie as well, which is not sharable between multiple servers by default.
Therefore, high availability has the following two requirements from an auth handler plugin: 1) The plugin
must state that it is HA capable by setting the capability flag haCompatible=true , usually indicating that
the plugin has no state data. 2) A plugin must have capability canGenerateHaSessionId=true so that
the zlux server cookie is sharable between multiple zlux servers.

REST API
Check status
Returns the current authentication status of the user to the caller.
Response example:
Every key in the response object is a registered auth type. The value object is guaranteed to have a Boolean
field named "authenticated" which indicates that at least one plugin in the category was able to authenticate
the user.
Each item also has a field called "plugins", where every property value is a plugin-specific object.

Authenticate
Authenticates the user against authentication back-ends.
Request body example:
The categories parameter is optional. If omitted, all auth plugins are invoked with the username and
password Response example:
First-level keys are authentication categories or types. "success" means that all of the types requested have
been successful. For example typeA successful AND typeB successful AND ...
Second-level keys are auth plugin IDs. "success" on this level means that there's at least one successful
result in that auth type. For example, pluginA successful OR pluginB successful OR ...

User not authenticated or not authorized

The response received by the browser when calling any service, when the user is either not authenticated or
not allowed to access the service.
Not authenticated
The client is supposed to address this by showing the user a login form which will later invoke the login
service for the plugin mentioned and repeat the request.
Not authorized
There's no general way for the client to address this, except than show the user an error message.
Refresh status
If you have an active session, some auth plugins may be able to renew the session. Not all plugins support
this action, so while the call may return successful, if there is an associated expiration time you may notice
that the expiration time has not changed or been reset.
{ "success": true, "categories": { "saf": { "success": true, "plugins": { "org.zowe.zlux.auth.safsso": {
"success": true "username":"foo", "expms": 60000 } } } } }
Logout
When you have an active session, you can terminate it early with a logout. This should remove cookies and
tell the server to clear any cache it had about a session.
Password changes
Some auth plugins will allow you to change your password. Depending on the backing security (such as
SAF), you may need to provide your current password to change it.
Internationalizing applications
Version: v2.0.x LTS

You can internationalize Zowe™ application plug-ins using Angular and React frameworks. Internationalized
applications display in translated languages and include structures for ongoing translation updates.
The steps below use the Zowe Sample Angular Application and Zowe Sample React Application as
examples. Your applications might have slightly different requirements, for example the React Sample
Application requires the react-i18next library, but your application might require a different React library.
For detailed information on Angular or React, see their documentation. For detailed information on specific
internationalization libraries, see their documentation. You can also reference the Sample Angular
Application internationalization tutorial, and watch a video on how to internationalize your Angular
application.
After you internationalize your application, you can view it by following steps in Changing the desktop
language.

Internationalizing Angular applications

Zowe applications that use the Angular framework depend on .xlf formatted files to store static
translated content and .json files to store dynamic translated content. These files must be in the
application's web/assets/i18n folder at runtime. Each translated language will have its own file.
To internationalize an application, you must install Angular-compatible internationalization libraries. Be aware
that libraries can be better suited to either static or dynamic HTML elements. The examples in this task use
the ngx-i18nsupport library for static content and angular-l10n for dynamic content.
To internationalize Zowe Angular applications, take the following steps:
. To install internationalization libraries, use the npm command, for example:
Note --save-dev commits the library to the application's required libraries list for future use.
. To support the CLI tools and to control output, create a webClient/tsconfig.i18n.json
typescript file and add the following content:
For example, see this file in the Sample Angular Application.
. In the static elements in your HTML files, tag translatable content with the i18n attribute within an
Angular template, for example:
The attribute should include a message ID, for example the @@welcome above.
. To configure static translation builds, take the following steps:
a. In the webClient/package.json script, add the following line:
b. In the in webClient directory, create a xliffmerge.json file, add the following content, and
specify the codes for each language you will translate in the languages parameter:
When you run the i18n script, it reads this file and generates a messages.[lang].xlf file in the
src/assets/i18n directory for each language specified in the languages parameter. Each file
contains the untranslated text from the i18n-tagged HTML elements.
. Run the following command to run the i18n script and extract i18n tagged HTML elements to .xlf
files:
Note If you change static translated content, you must run the npm run build command to build
the application, and then re-run the npm run i18n command to extract the tagged content again.
. In each .xlf file, replace target element strings with translated versions of the source element
strings. For example:
. Run the following command to rebuild the application:
When you switch the Zowe Desktop to one of the application's translated languages, the application
displays the translated strings.
. For dynamic translated content, follow these steps:
a. Import and utilize angular-l10n objects within an Angular component, for example:
b. In the related Angular template, you can implement myDynamicMessage as an ordinary
substitutable string, for example:
. Create logic to copy the translation files to the web/assets directory during the webpack process,
for example in the sample application, the following JavaScript in the copy-webpack-plugin file
copies the files:
 Note: Do not edit files in the web/assets/i18n directory. They are overwritten by each build.

Internationalizing React applications

To internationalize Zowe applications using the React framework, take the following steps:
Note: These examples use the recommended react-i18next library, which does not differentiate between
dynamic and static content, and unlike the Angular steps above does not require a separate build process.
. To install the React library, run the following command:
npm install --save-dev react-i18next

. In the directory that contains your index.js file, create an i18n.js file and add the translated
content, for example:
. Import the i18n file from the previous step into index.js file so that you can use it elsewhere, for
example:
. To internationalize a component, include the useTranslation hook and reference it to substitute
translation keys with their translated values. For example:

Internationalizing application desktop titles

To display the translated application name and description in the Desktop, take the following steps:
. For each language, create a pluginDefinition.i18n.<lang_code>.json file. For example, for
German create a pluginDefinition.i18n.de.json file.
. Place the .json files in the web/assets/i18n directory.
. Translate the pluginShortNameKey and descriptionKey values in the application's
pluginDefinition.json file. For example, for the file below you would translate the values
"sampleangular" and "sampleangulardescription" :

. Add the translated values to the translation file. For example, the German translation file example,
pluginDefinition.i18n.de.json , would look like this:
. Create logic to copy the translation files to the web/assets directory during the webpack process.
For example, in the Sample Angular Application the following JavaScript in the
webClient/webpack.config.js file copies files to the web/assets directory:
Zowe Desktop and window management
Version: v2.0.x LTS

The Zowe™ Desktop is a web component of Zowe, which is an implementation of

MVDWindowManagement , the interface that is used to create a window manager.

The code for this software is in the zlux-app-manager repository.

The interface for building an alternative window manager is in the zlux-platform repository.
Window Management acts upon Windows, which are visualizations of an instance of an application plug-in.
Application plug-ins are plug-ins of the type "application", and therefore the Zowe Desktop operates around
a collection of plug-ins.
Note: Other objects and frameworks that can be utilized by application plug-ins, but not related to window
management, such as application-to-application communication, Logging, URI lookup, and Auth are not
described here.

Loading and presenting application plug-ins

Upon loading the Zowe Desktop, a GET call is made to /plugins?type=application . The GET call
returns a JSON list of all application plug-ins that are on the server, which can be accessed by the user.
Application plug-ins can be composed of dataservices, web content, or both. Application plug-ins that have
web content are presented in the Zowe Desktop UI.
The Zowe Desktop has a taskbar at the bottom of the page, where it displays each application plug-in as an
icon with a description. The icon that is used, and the description that is presented are based on the
application plug-in's PluginDefinition 's webContent attributes.

Plug-in management
Application plug-ins can gain insight into the environment in which they were spawned through the Plugin
Manager. Use the Plugin Manager to determine whether a plug-in is present before you act upon the
existence of that plug-in. When the Zowe Desktop is running, you can access the Plugin Manager through
ZoweZLUX.PluginManager

The following are the functions you can use on the Plugin Manager:
 getPlugin(pluginID: string)
Accepts a string of a unique plug-in ID, and returns the Plugin Definition Object
(DesktopPluginDefinition) that is associated with it, if found.

Application management
Application plug-ins within a Window Manager are created and acted upon in part by an Application
Manager. The Application Manager can facilitate communication between application plug-ins, but formal
application-to-application communication should be performed by calls to the Dispatcher. The Application
Manager is not normally directly accessible by application plug-ins, instead used by the Window Manager.
The following are functions of an Application Manager:
Function Description
spawnApplication(plugin:
Opens an application instance into the Window
DesktopPluginDefinition,
Manager, with or without context on what
launchMetadata: any):
Promise<MVDHosting.InstanceId>;
actions it should perform after creation.

killApplication(plugin:ZLUX.Plugin, Removes an application instance from the

appId:MVDHosting.InstanceId): void; Window Manager.
showApplicationWindow(plugin: Makes an open application instance visible
DesktopPluginDefinitionImpl): void; within the Window Manager.
isApplicationRunning(plugin: Determines if any instances of the application
DesktopPluginDefinitionImpl): boolean; are open in the Window Manager.

Windows and Viewports

When a user clicks an application plug-in's icon on the taskbar, an instance of the application plug-in is
started and presented within a Viewport, which is encapsulated in a Window within the Zowe Desktop. Every
instance of an application plug-in's web content within Zowe is given context and can listen on events about
the Viewport and Window it exists within, regardless of whether the Window Manager implementation
utilizes these constructs visually. It is possible to create a Window Manager that only displays one
application plug-in at a time, or to have a drawer-and-panel UI rather than a true windowed UI.
When the Window is created, the application plug-in's web content is encapsulated dependent upon its
framework type. The following are valid framework types:
"angular2": The web content is written in Angular, and packaged with Webpack. Application plug-in
framework objects are given through @injectables and imports.
"iframe": The web content can be written using any framework, but is included through an iframe tag.
Application plug-ins within an iframe can access framework objects through parent.RocketMVD and
callbacks.
"react": The web content is written in React, Typescript, and packaged with Webpack. App framework
objects are provided via the ReactMVDResources object
In the case of the Zowe Desktop, this framework-specific wrapping is handled by the Plugin Manager.

Viewport Manager
Viewports encapsulate an instance of an application plug-in's web content, but otherwise do not add to the
UI (they do not present Chrome as a Window does). Each instance of an application plug-in is associated
with a viewport, and operations to act upon a particular application plug-in instance should be done by
specifying a viewport for an application plug-in, to differentiate which instance is the target of an action.
Actions performed against viewports should be performed through the Viewport Manager.
The following are functions of the Viewport Manager:
Function Description
createViewport(providers: Creates a viewport into which an
ResolvedReflectiveProvider[]): application plug-in's webcontent can be
MVDHosting.ViewportId; embedded.
registerViewport(viewportId:
Registers a previously created viewport
MVDHosting.ViewportId, instanceId:
MVDHosting.InstanceId): void;
to an application plug-in instance.
 Function Description
destroyViewport(viewportId: Removes a viewport from the Window
MVDHosting.ViewportId): void; Manager.
`getApplicationInstanceId(viewportId: null;`
MVDHosting.ViewportId): MVDHosting.InstanceId

Injection Manager
When you create Angular application plug-ins, they can use injectables to be informed of when an action
occurs. iframe application plug-ins indirectly benefit from some of these hooks due to the wrapper acting
upon them, but Angular application plug-ins have direct access.
The following topics describe injectables that application plug-ins can use.
Plug-in definition
Provides the plug-in definition that is associated with this application plug-in. This injectable can be used to
gain context about the application plug-in. It can also be used by the application plug-in with other
application plug-in framework objects to perform a contextual action.
Logger
Provides a logger that is named after the application plug-in's plugin definition ID.
Launch Metadata
If present, this variable requests the application plug-in instance to initialize with some context, rather than
the default view.
Viewport Events
Presents hooks that can be subscribed to for event listening. Events include:
resized: Subject<{width: number, height: number}>
Fires when the viewport's size has changed.
Window Events
Presents hooks that can be subscribed to for event listening. The events include:
Event Description
maximized: Subject<void> Fires when the Window is maximized.
minimized: Subject<void> Fires when the Window is minimized.
Fires when the Window is restored from a
restored: Subject<void>
minimized state.
moved: Subject<{top: number, left:
number}>
Fires when the Window is moved.

resized: Subject<{width: number, height:

number}>
Fires when the Window is resized.

titleChanged: Subject<string> Fires when the Window's title changes.

Window Actions
An application plug-in can request actions to be performed on the Window through the following:
Item Description
Closes the Window of the application plug-in
close(): void
instance.
Maximizes the Window of the application plug-
maximize(): void
in instance.
 Item Description
Minimizes the Window of the application plug-in
minimize(): void
instance.
Restores the Window of the application plug-in
restore(): void
instance from a minimized state.
setTitle(title: string):void Sets the title of the Window.
setPosition(pos: {top: number, left:
Sets the position of the Window on the page
number, width: number, height: number}):
void
and the size of the window.

Opens a context menu on the application plug-

spawnContextMenu(xPos: number, yPos:
in instance, which uses the Context Menu
number, items: ContextMenuItem[]): void
framework.
Registers a handler, which is called when the
registerCloseHandler(handler: () =>
Window and application plug-in instance are
Promise<void>): void
closed.

Framework API examples

The following are examples of how you would access the Window Actions API to begin an App in maximized
mode upon start-up.
Angular
. Import Angular2InjectionTokens from 'pluginlib/inject-resources'
. Within the constructor of your App, in the arguments, do @Optional()
@Inject(Angular2InjectionTokens.WINDOW_ACTIONS) private windowActions:
Angular2PluginWindowActions

. Then inside the constructor, check that window actions exist and then execute the action if
(this.windowActions) { this.windowActions.maximize(); }
 . Depending on your App layout, certain UI elements may not have loaded so to wait for them to load, one
may want to use something like Angular's NgOnInit directive.
React
. Similar to how we do things in Angular, except the Window Actions (& other Zowe resources) are
located in the resources object. So if we were using a React.Component, we could have a
constructor with constructor(props){ super(props); ... }
. Then accessing Window Actions would be as simple as this.props.resources.windowActions
IFrames
. Iframes are similar to Angular & React, but require a different import step. Instead to use Window
Actions (& other Zowe resources), we have to import the Iframe adapter. The Iframe adapter is located
in zlux-app-manager/bootstrap/web/iframe-adapter.js so something like a relative path in
my JS code will suffice,
<script type="text/javascript" src="../../../org.zowe.zlux.bootstrap/web/iframe-
adapter.js"></script>

. Then to use Window Actions would be as simple as await windowActions.minimize();

NOTE: The Iframe adapter is not yet feature-complete. If you are attempting to use an event supported by
Angular or React, but not yet supported in Iframes, try to use the window.parent.ZoweZLUX object
instead.
Configuration Dataservice
Version: v2.0.x LTS

The Configuration Dataservice is an essential component of the Zowe™ Application Framework, which acts
as a JSON resource storage service, and is accessible externally by REST API and internally to the server by
dataservices.
The Configuration Dataservice allows for saving preferences of applications, management of defaults and
privileges within a Zowe ecosystem, and bootstrapping configuration of the server's dataservices.
The fundamental element of extensibility of the Zowe Application Framework is a plug-in. The Configuration
Dataservice works with data for plug-ins. Every resource that is stored in the Configuration Service is stored
for a particular plug-in, and valid resources to be accessed are determined by the definition of each plug-in
in how it uses the Configuration Dataservice.
The behavior of the Configuration Dataservice is dependent upon the Resource structure for a plug-in. Each
plug-in lists the valid resources, and the administrators can set permissions for the users who can view or
modify these resources.
. Resource Scope
. REST API
i. REST Query Parameters
ii. REST HTTP Methods
a. GET
b. PUT
c. DELETE
iii. Administrative Access & Group
. App API
. Internal and Bootstrapping
. Packaging Defaults
. Plugin Definition
. Aggregation Policies
. Examples

Resource Scope
Data is stored within the Configuration Dataservice according to the selected Scope. The intent of Scope
within the Dataservice is to facilitate company-wide administration and privilege management of Zowe data.
When a user requests a resource, the resource that is retrieved is an override or an aggregation of the
broader scopes that encompass the Scope from which they are viewing the data.
When a user stores a resource, the resource is stored within a Scope but only if the user has access
privilege to update within that Scope.
Scope is one of the following:
Plugin
Configuration defaults that come with a plugin. Cannot be modified.
Product
Configuration defaults that come with the product. Cannot be modified.
Site
Data that can be used between multiple instances of the Zowe Application Server.
Instance
Data within an individual Zowe Application Server.
Group
Data that is shared between multiple users in a group.(Pending)
User
Data for an individual user.(Pending)
Note: While Authorization tuning can allow for settings such as GET from Instance to work without login,
User and Group scope queries will be rejected if not logged in due to the requirement to pull resources from
a specific user. Because of this, User and Group scopes will not be functional until the Security Framework is
merged into the mainline.
Where Plugin is the broadest scope and User is the narrowest scope.
When you specify Scope User, the service manages configuration for your particular username, using the
authentication of the session. This way, the User scope is always mapped to your current username.
Consider a case where a user wants to access preferences for their text editor. One way they could do this is
to use the REST API to retrieve the settings resource from the Instance scope.
The Instance scope might contain editor defaults set by the administrator. But, if there are no defaults in
Instance, then the data in Group and User would be checked.
Therefore, the data the user receives would be no broader than what is stored in the Instance scope, but
might have only been the settings they saved within their own User scope (if the broader scopes do not have
data for the resource).
Later, the user might want to save changes, and they try to save them in the Instance scope. Most likely, this
action will be rejected because of the preferences set by the administrator to disallow changes to the
Instance scope by ordinary users.

REST API
When you reach the Configuration Service through a REST API, HTTP methods are used to perform the
desired operation.
The HTTP URL scheme for the configuration dataservice is:
<Server>/plugins/com.rs.configjs/services/data/<plugin
ID>/<Scope>/<resource>/<optional subresources>?<query>

Where the resources are one or more levels deep, using as many layers of subresources as needed.
Think of a resource as a collection of elements, or a directory. To access a single element, you must use the
query parameter "name="
REST query parameters
Name (string)
Get or put a single element rather than a collection.
Recursive (boolean)
When performing a DELETE, specifies whether to delete subresources too.
Listing (boolean)
When performing a GET against a resource with content subresources, listing=true will provide the
names of the subresources rather than both the names and contents.
REST HTTP methods
Below is an explanation of each type of REST call.
Each API call includes an example request and response against a hypothetical application called the "code
editor".
GET
GET /plugins/com.rs.configjs/services/data/<plugin>/<scope>/<resource>?name=
<element>

This returns JSON with the attribute "content" being a JSON resource that is the entire configuration
that was requested. For example:
/plugins/com.rs.configjs/services/data/org.openmainframe.zowe.codeeditor/user
/sessions/default?name=tabs

The parts of the URL are:

Plugin: org.openmainframe.zowe.codeeditor
Scope: user
Resource: sessions
Subresource: default
Element = tabs
The response body is a JSON config:
GET /plugins/com.rs.configjs/services/data/<plugin>/<scope>/<resource>
This returns JSON with the attribute content being a JSON object that has each attribute being another
JSON object, which is a single configuration element.
GET /plugins/com.rs.configjs/services/data/<plugin>/<scope>/<resource>
(When subresources exist.)
This returns a listing of subresources that can, in turn, be queried.
PUT
PUT /plugins/com.rs.configjs/services/data/<plugin>/<scope>/<resource>?name=
<element>

Stores a single element (must be a JSON object {...}) within the requested scope, ignoring aggregation
policies, depending on the user privilege. For example:
/plugins/com.rs.configjs/services/data/org.openmainframe.zowe.codeeditor/user/ses
sions/default?name=tabs

Body:
Response:
DELETE
DELETE /plugins/com.rs.configjs/services/data/<plugin>/<scope>/<resource>?
recursive=true

Deletes all files in all leaf resources below the resource specified.
DELETE /plugins/com.rs.configjs/services/data/<plugin>/<scope>/<resource>?name=
<element>

Deletes a single file in a leaf resource.

DELETE /plugins/com.rs.configjs/services/data/<plugin>/<scope>/<resource>
Deletes all files in a leaf resource.
Does not delete the directory on disk.
Administrative access and group
By means not discussed here, but instead handled by the server's authentication and authorization code, a
user might be privileged to access or modify items that they do not own.
In the simplest case, it might mean that the user is able to do a PUT, POST, or DELETE to a level above User,
such as Instance.
The more interesting case is in accessing another user's contents. In this case, the shape of the URL is
different. Compare the following two commands:
GET /plugins/com.rs.configjs/services/data/<plugin>/user/<resource>
Gets the content for the current user.
GET /plugins/com.rs.configjs/services/data/<plugin>/users/<username>/<resource>
Gets the content for a specific user if authorized.
This is the same structure that is used for the Group scope. When requesting content from the Group scope,
the user is checked to see if they are authorized to make the request for the specific group. For example:
GET /plugins/com.rs.configjs/services/data/<plugin>/group/<groupname>/<resource>
Gets the content for the given group, if the user is authorized.

Application API
Retrieves and stores configuration information from specific scopes.
Note: This API should only be used for configuration administration user interfaces.
ZLUX.UriBroker.pluginConfigForScopeUri(pluginDefinition: ZLUX.Plugin, scope:
string, resourcePath:string, resourceName:string): string;

A shortcut for the preceding method, and the preferred method when you are retrieving configuration
information, is simply to "consume" it. It "asks" for configurations using the User scope, and allows the
configuration service to decide which configuration information to retrieve and how to aggregate it. (See
below on how the configuration service evaluates what to return for this type of request).
ZLUX.UriBroker.pluginConfigUri(pluginDefinition: ZLUX.Plugin,
resourcePath:string, resourceName:string): string;
Internal and bootstrapping
Some dataservices within plug-ins can take configuration that affects their behavior. This configuration is
stored within the Configuration Dataservice structure, but it is not accessible through the REST API.
Within the instance configuration directory of a zLUX installation, each plugin may optionally have an
_internal directory. An example of such a path would be:

~/.zowe/workspace/app-server/ZLUX/pluginStorage/<pluginName>/_internal

Within each _internal directory, the following directories might exist:

services/<servicename> : Configuration resources for the specific service.

plugin : Configuration resources that are visible to all services in the plug-in.

The JSON contents within these directories are provided as Objects to dataservices through the dataservice
context Object.

Packaging Defaults
The best way to provide default settings for a plugin is to include it as part of the plugin's package.
It's easy to distribute to users, requires no configuration steps, and is read-only from the server.
To package, all content must be stored within the /config/storageDefaults directory of your plugin.
Within, non-leaf resources are folders, and leaf resources are files, regardless of JSON or binary.
The _internal folder and content is also permitted.

Plug-in definition
Because the Configuration Dataservices stores data on a per-plug-in basis, each plug-in must define their
resource structure to make use of the Configuration Dataservice. The resource structure definition is
included in the plug-in's pluginDefinition.json file.
For each resource and subresource, you can define an aggregationPolicy to control how the data of a
broader scope alters the resource data that is returned to a user when requesting a resource from a
narrower Scope.
For example:
Aggregation policies
Aggregation policies determine how the Configuration Dataservice aggregates JSON objects from different
Scopes together when a user requests a resource. If the user requests a resource from the User scope, the
data from the User scope might replace or be merged with the data from a broader scope such as Instance,
to make a combined resource object that is returned to the user.
Aggregation policies are defined by a plug-in developer in the plug-in's definition for the Configuration
Service, as the attribute aggregationPolicy within a resource.
The following policies are currently implemented:
NONE: If the Configuration Dataservice is called for Scope User, only user-saved settings are sent,
unless there are no user-saved settings for the query, in which case the dataservice attempts to send
data that is found at a broader scope.
OVERRIDE: The Configuration Dataservice obtains data for the resource that is requested at the
broadest level found, and joins the resource's properties from narrower scopes, overriding broader
attributes with narrower ones, when found.

Examples
zlux-app-manager VT Terminal App
URI Broker
Version: v2.0.x LTS

The URI Broker is an object in the application plug-in web framework, which facilitates calls to the Zowe™
Application Server by constructing URIs that use the context from the calling application plug-in.
. Accessing the URI Broker
i. Natively
ii. In an iframe
. Functions
i. Accessing an application plug-in's dataservices
a. HTTP dataservice URI
b. Websocket dataservice URI
ii. Accessing the application plug-in's configuration resources
a. Standard configuration access
b. Scoped configuration access
iii. Accessing static content
iv. Accessing the application plug-in's root
v. Server queries
a. Accessing list of plugins

Accessing the URI Broker

The URI Broker is accessible independent of other frameworks involved such as Angular, and is also
accessible through iframe. This is because it is attached to a global when within the Zowe Desktop. For more
information, see Zowe Desktop and window management. Access the URI Broker through one of two
locations:
Natively:
window.ZoweZLUX.uriBroker

In an iframe:
window.parent.ZoweZLUX.uriBroker
Functions
The URI Broker builds the following categories of URIs depending upon what the application plug-in is
designed to call.
Accessing an application plug-in's dataservices
Dataservices can be based on HTTP (REST) or Websocket. For more information, see Dataservices.
HTTP Dataservice URI
pluginRESTUri(plugin:ZLUX.Plugin, serviceName: string, relativePath:string):
string

Returns: A URI for making an HTTP service request.

Websocket Dataservice URI
pluginWSUri(plugin: ZLUX.Plugin, serviceName:string, relativePath:string):
string

Returns: A URI for making a Websocket connection to the service.

Accessing application plug-in's configuration resources
Defaults and user storage might exist for an application plug-in such that they can be retrieved through the
Configuration Dataservice.
There are different scopes and actions to take with this service, and therefore there are a few URIs that can
be built:
Standard configuration access
pluginConfigUri(pluginDefinition: ZLUX.Plugin, resourcePath:string,
resourceName?:string): string

Returns: A URI for accessing the requested resource under the user's storage.
Scoped configuration access
pluginConfigForScopeUri(pluginDefinition: ZLUX.Plugin, scope: string,
resourcePath:string, resourceName?:string): string

Returns: A URI for accessing a specific scope for a given resource.

Accessing static content
Content under an application plug-in's web directory is static content accessible by a browser. This can be
accessed through:
pluginResourceUri(pluginDefinition: ZLUX.Plugin, relativePath: string): string

Returns: A URI for getting static content.

For more information about the web directory, see Application plug-in filesystem structure.
Accessing the application plug-in's root
Static content and services are accessed off of the root URI of an application plug-in. If there are other
points that you must access on that application plug-in, you can get the root:
pluginRootUri(pluginDefinition: ZLUX.Plugin): string

Returns: A URI to the root of the application plug-in.

Server queries
A client can find different information about a server's configuration or the configuration as seen by the
current user by accessing specific APIs.
Accessing a list of plug-ins
pluginListUri(pluginType: ZLUX.PluginType): string

Returns: A URI, which when accessed returns the list of existing plug-ins on the server by type, such as
"Application" or "all".
Application-to-application communication
Version: v2.0.x LTS

Zowe™ application plug-ins can opt-in to various application framework abilities, such as the ability to have a
Logger, the ability to use a URI builder utility, and more.
The ability for one appliccation plug-in to communicate with another is an ability that is unique to Zowe
environments with multiple application plug-ins. The application framework provides constructs that
facilitate this ability.
The constructs are: the Dispatcher, Actions, Recognizers, Registry, and the features that utilize them such as
the framework's Context menu.
. Why use application-to-application communication?
. Actions
. Recognizers
. Dispatcher
. URI Parameters

Why use application-to-application communication?

When working with computers, people often use multiple applications to accomplish a task. For example, a
person might check their email before opening a bank statement in a browser. In many environments, the
relationship between one application and another is not well defined. For example, you may open one
program to learn of a situation, which is then resolved by opening a different program and typing in content.
The application framework attempts to solve this problem by creating structured messages that can be sent
from one application plug-in to another.
An application plug-in has a context of the information that it contains. This context can be used to invoke an
action on another application plug-in that is better suited to handle some of the information discovered in
the first application plug-in. Well-structured messages facilitate the process of determining which
application plug-in is best suited to handle a given situation, while also explaining, in detail, what that
application plug-in should do.
This way, rather than finding out that an attachment with the extension ".dat" was not meant for a text editor,
but rather for an email client, one application plug-in may be able to invoke an action on an application plug-
in that is capable of opening of an email.
Actions
To manage communication from one application plug-in to another, a specific structure is needed. In the
application framework, the unit of application-to-application communication is an Action. The typescript
definition of an Action is as follows:
An Action has a specific structure of data that is passed, to be filled in with the context at runtime, and a
specific target to receive the data.
The Action is dispatched to the target in one of several modes, for example: to target a specific instance of
an application plug-in, an instance, or to create a new instance.
The Action can be less detailed than a message. It can be a request to minimize, maximize, close, launch,
and more. Finally, all of this information is related to a unique ID and localization string such that it can be
managed by the framework.
Action target modes
When you request an Action on an application plug-in, the behavior is dependent on the instance of the
application plug-in you are targeting. You can instruct the framework to target the application plug-in with a
target mode from the ActionTargetMode enum :
Action types
The application framework performs different operations on application plug-ins depending on the type of
an Action. The behavior can be quite different, from simple messaging to requesting that an application
plug-in be minimized. The types are defined by an enum :
Loading actions
Actions can be created dynamically at runtime, or saved and loaded by the system at login.
App2App via URL
Another way the Zowe Application Framework invokes Actions is via URL Query Parameters, with
parameters formatted in JSON. This feature enables users to bookmark a set of application-to-application
communication actions (in the form of a URL) that will be executed when opening the webpage. Developers
creating separate web apps can build a link that will open the Zowe Desktop and do specific actions in Apps,
for example, opening a file in the Editor.
The App2App via URL feature allows you to:
. Specify one or more actions that will be executed upon login, allowing you to bookmark a series of
actions that you can share with someone else.
. Specify actions that are declared by plugins (when formatter is equal to a known action ID) or actions
that you have custom-made (when formatter = 'data').
. Customize the action type, mode, and target plugin (when the formatter is equal to an existing action
ID).
Samples
Query parameter format:
?app2app={pluginId}:{actionType}:{actionMode}:{formatter}:{contextData}&app2app=
{pluginId}:{actionType}:{actionMode}:{formatter}:{contextData}

pluginId - application identifier, e.g. 'org.zowe.zlux.ng2desktop.webbrowser'

actionType - 'launch' | 'message'

actionMode - 'create' | 'system'

formatter - 'data' | actionId

contextData - context data in form of JSON

windowManager - 'MVD' | undefined : (Optional) While in standalone mode, controls whether

to use the Zowe (MVD) window manager or the deprecated simple window manager. Default is MVD.
showLogin - true | false : (Optional) While in standalone mode, controls whether to show
Zowe's login page if credentials are not retrieved from a previous Desktop session, or if to disable it and
load the application anyway (ideal solution for apps with their own login experiences). Default is true.
Note that some of these parameters are shared with single app mode, therefore, you may need to adjust
pluginId and app2app parameters as follows
(desktop mode)
(single app mode)
Dynamically
You can create Actions by calling the following Dispatcher method: makeAction(id: string,
defaultName: string, targetMode: ActionTargetMode, type: ActionType,
targetPluginID: string, primaryArgument: any):Action

Saved on system
Actions can be stored in JSON files that are loaded at login. The JSON structure is as follows:

Recognizers
Actions are meant to be invoked when certain conditions are met. For example, you do not need to open a
messaging window if you have no one to message. Recognizers are objects within the application framework
that use the context that the application plug-in provides to determine if there is a condition for which it
makes sense to execute an Action. Each recognizer has statements about what condition to recognize, and
when that statement is met, which Action can be executed at that time. The invocation of the Action is not
handled by the Recognizer; it simply detects that an Action can be taken.
Recognition clauses
Recognizers associate a clause of recognition with an action, as you can see from the following class:
A clause, in turn, is associated with an operation, and the subclauses upon which the operation acts. The
following operations are supported:
Loading Recognizers at runtime
You can add a Recognizer to the application plug-in environment in one of two ways: by loading from
Recognizers saved on the system, or by adding them dynamically.
Dynamically
You can call the Dispatcher method, addRecognizer(predicate:RecognitionClause,
actionID:string):void

Saved on system
Recognizers can be stored in JSON files that are loaded at login. The JSON structure is as follows:
clause can take on one of two shapes:
Or,
Where this one can again, have subclauses.
Recognizer example
Recognizers can be as simple or complex as you write them to be, but here is an example to illustrate the
mechanism:
In this case, the Recognizer detects whether it is possible to run the org.zowe.explorer.openmember
Action when the TN3270 Terminal application plug-in is on the screen ISRUDSM (an ISPF panel for browsing
PDS members).

Dispatcher
The dispatcher is a core component of the application framework that is accessible through the Global
ZLUX Object at runtime. The Dispatcher interprets Recognizers and Actions that are added to it at runtime.
You can register Actions and Recognizers on it, and later, invoke an Action through it. The dispatcher
handles how the Action's effects should be carried out, acting in combination with the Window Manager and
application plug-ins to provide a channel of communication.

Registry
The Registry is a core component of the application framework, which is accessible through the Global
ZLUX Object at runtime. It contains information about which application plug-ins are present in the
environment, and the abilities of each application plug-in. This is important to application-to-application
communication, because a target might not be a specific application plug-in, but rather an application plug-
in of a specific category, or with a specific featureset, capable of responding to the type of Action requested.

Pulling it all together in an example

The standard way to make use of application-to-application communication is by having Actions and
Recognizers that are saved on the system. Actions and Recognizers are loaded at login, and then later,
through a form of automation or by a user action, Recognizers can be polled to determine if there is an
Action that can be executed. All of this is handled by the Dispatcher, but the description of the behavior lies
in the Action and Recognizer that are used. In the Action and Recognizer descriptions above, there are two
JSON definitions: One is a Recognizer that recognizes when the Terminal application plug-in is in a certain
state, and another is an Action that instructs the MVS Explorer to load a PDS member for editing. When you
put the two together, a practical application is that you can launch the MVS Explorer to edit a PDS member
that you have selected within the Terminal application plug-in.
Configuring IFrame communication
Version: v2.0.x LTS

The Zowe Application Framework provides the following shared resource functions through a ZoweZLUX
object: pluginManager , uriBroker , dispatcher , logger , registry ,
notificationManager , and globalization

Like REACT and Angular apps, IFrame apps can use the ZoweZLUX object to communicate with the
framework and other apps. To enable communication in an IFrame app, you must add the following
javascript to your app, for example in your index.html file:
logger.js is the javascript version of logger.ts and is capable of the same functions, including
access to the Logger and ComponentLogger classes. The Logger class determines the behavior of
all the ComponentLoggers created from it. ComponentLoggers are what the user implements to
perform logging.
Iframe-adapter.js is designed to mimic the ZoweZLUX object that is available to apps within the
virtual-desktop, and serves as the middle-man for communication between IFrame apps and the Zowe
desktop.
You can see an implementation of this functionality in the sample IFrame app.
The version of ZoweZLUX adapted for IFrame apps is not complete and only implements the functions
needed to allow the Sample IFrame App to function. The notificationManager , logger ,
globalization , dispatcher , windowActions , windowEvents , and viewportEvents are fully
implemented. The pluginManager and uriBroker are only partially implemented. The registry is
not implemented.
Unlike REACT and Angular apps, in IFrame apps the ZoweZLUX and initialization objects communicate with
Zowe using the browser's onmessage and postmessage APIs. That means that communication operations
are asynchronous, and you must account for this in your app, for example by using Promise objects and
await or then functions.
Error reporting UI
Version: v2.0.x LTS

The zLUX Widgets repository contains shared widget-like components of the Zowe™ Desktop, including
Button, Checkbox, Paginator, various pop-ups, and others. To maintain consistency in desktop styling across
all applications, use, reuse, and customize existing widgets to suit the purpose of the application's function
and look.
Ideally, a program should have little to no logic errors. Once in a while a few occur, but more commonly an
error occurs from misconfigured user settings. A user might request an action or command that requires
certain prerequisites, for example: a proper ZSS-Server configuration. If the program or method fails, the
program should notify the user through the UI about the error and how to fix it. For the purposes of this
discussion, we will use the Workflow application plug-in in the zlux-workflow repository.

ZluxPopupManagerService
The ZluxPopupManagerService is a standard popup widget that can, through its reportError()
method, be used to display errors with attributes that specify the title or error code, severity, text, whether it
should block the user from proceeding, whether it should output to the logger, and other options you want
to add to the error dialog. ZluxPopupManagerService uses both ZluxErrorSeverity and
ErrorReportStruct .

ZluxErrorSeverity
ZluxErrorSeverity classifies the type of report. Under the popup-manager, there are the following
types: error, warning, and information. Each type has its own visual style. To accurately indicate the type of
issue to the user, the error or pop-up should be classified accordingly.

ErrorReportStruct
ErrorReportStruct contains the main interface that brings the specified parameters of
reportError() together.

Implementation
Import ZluxPopupManagerService and ZluxErrorSeverity from widgets. If you are using
additional services with your error prompt, import those too (for example, LoggerService to print to the
logger or GlobalVeilService to create a visible semi-transparent gray veil over the program and pause
background tasks). Here, widgets is imported from node_modules\@zlux\ so you must ensure zLUX
widgets is used in your package-lock.json or package.json and you have run npm install .
import { ZluxPopupManagerService, ZluxErrorSeverity } from '@zlux/widgets';

Declaration
Create a member variable within the constructor of the class you want to use it for. For example, in the
Workflow application plug-in under \zlux-workflow\src\app\app\zosmf-server-
config.component.ts is a ZosmfServerConfigComponent class with the pop-up manager service
variable. To automatically report the error to the console, you must set a logger.
Usage
Now that you have declared your variable within the scope of your program's class, you are ready to use the
method. The following example describes an instance of the reload() method in Workflow that catches
an error when the program attempts to retrieve a configuration from a configService and set it to the
program's this.config . This method fails when the user has a faulty zss-Server configuration and the
error is caught and then sent to the class' popupManager variable from the constructor above.
Here, the errorMessage clearly describes the error with a small degree of ambiguity as to account for all
types of errors that might occur from that method. The specifics of the error are then generated dynamically
and are printed with the err.toString() , which contains the more specific information that is used to
pinpoint the problem. The this.popupManager.report() method triggers the error prompt to display.
The error severity is set with ZluxErrorSeverity.ERROR and the err.status.toString()
describes the status of the error (often classified by a code, for example: 404 ). The optional parameters in
options specify that this error will block the user from interacting with the application plug-in until the
error is closed or it until goes away on its own. globalVeilService is optional and is used to create a
gray veil on the outside of the program when the error is caused. You must import globalVeilService
separately (see the zlux-workflow repository for more information).
HTML
The final step is to have the recently created error dialog display in the application plug-in. If you do
this.popupManager.report() without adding the component to your template, the error will not be
displayed. Navigate to your component's .html file. On the Workflow application plug-in, this file will be in
\zlux-workflow\src\app\app\zosmf-server-config.component.html and the only item left is
to add the popup manager component alongside your other classes.
<zlux-popup-manager></zlux-popup-manager>

So now when the error is called, the new UI element should resemble the following:

The order in which you place the pop-up manager determines how the error dialog will overlap in your UI. If
you want the error dialog to overlap other UI elements, place it at the end of the .html file. You can also
create custom styling through a CSS template, and add it within the scope of your application plug-in.
Logging utility
Version: v2.0.x LTS

The zlux-shared repository provides a logging utility for use by dataservices and web content for an
application plug-in.
. Logging Objects
. Logger IDs
. Accessing Logger Objects
i. Logger
a. App Server
b. Web
ii. Component Logger
a. App Server
b. Web
. Logger API
. Component Logger API
. Log Levels
. Logging Verbosity
i. Configuring Logging Verbosity
a. Server Startup Logging Configuration
. Using log message IDs

Logging objects
The logging utility is based on the following objects:
Component Loggers: Objects that log messages for an individual component of the environment, such
as a REST API for an application plug-in or to log user access.
Destinations: Objects that are called when a component logger requests a message to be logged.
Destinations determine how something is logged, for example, to a file or to a console, and what
formatting is applied.
Logger: Central logging object, which can spawn component loggers and attach destinations.
Logger IDs
Because Zowe™ application plug-ins have unique identifiers, both dataservices and an application plug-in's
web content are provided with a component logger that knows this unique ID such that messages that are
logged can be prefixed with the ID. With the association of logging to IDs, you can control verbosity of logs
by setting log verbosity by ID.

Accessing logger objects

Logger
The core logger object is attached as a global for low-level access.
App Server
NodeJS uses global as its global object, so the logger is attached to:
global.COM_RS_COMMON_LOGGER

Web
(Angular App Instance Injectible). See Logger in Zowe Desktop and window management.
(others) Browsers use window as the global object, so the logger is attached to:
window.COM_RS_COMMON_LOGGER

Component logger
Component loggers are created from the core logger object, but when working with an application plug-in,
allow the application plug-in framework to create these loggers for you. An application plug-in's component
logger is presented to dataservices or web content as follows.
App Server
See Router Dataservice Context in the topic Dataservices.

Logger API
The following constants and functions are available on the central logging object.
 Attribute Type Description Arguments
Returns an existing
logger of this name, or
creates a new
component logger if
no logger of the
makeComponentLogger function specified name exists componentIDString
- Automatically done
by the application
framework for
dataservices and web
content
Sets the verbosity of ,
setLogLevelForComponentName function an existing component componentIDString

logger logLevel

Component Logger API

The following constants and functions are available to each component logger.
Attribute Type Description Arguments
CRITICAL const Is a const for logLevel
SEVERE const Is a const for logLevel
WARN const Is a const for logLevel
WARNING const Is a const for logLevel
INFO const Is a const for logLevel
DEBUG const Is a const for logLevel
 Attribute Type Description Arguments
FINE const Is a const for logLevel
FINER const Is a const for logLevel
TRACE const Is a const for logLevel
FINEST const Is a const for logLevel

function Used to write a log, specifying the log logLevel ,

log
level messageString

critical function Used to write a CRITICAL log. messageString

severe function Used to write a SEVERE log. messageString

warn function Used to write a WARNING log. messageString

info function Used to write an INFO log. messageString

debug function Used to write a FINE log. messageString

trace function Used to write a TRACE log. messageString

makeSublogger function Creates a new component logger with

an ID appended by the string given componentNameSuffix

Log Levels
An enum, LogLevel , exists for specifying the verbosity level of a logger. The mapping is:
Level Number
CRITICAL 0
 Level Number
WARNING 1
INFO 2
DEBUG 3
FINER 4
TRACE 5
Note: The default log level for a logger is INFO.

Logging verbosity
Using the component logger API, loggers can dictate at which level of verbosity a log message should be
visible. You can configure the server or client to show more or less verbose messages by using the core
logger's API objects.
Example: You want to set the verbosity of the org.zowe.foo application plug-in's dataservice, bar to show
debugging information.
logger.setLogLevelForComponentName('org.zowe.foo.bar',LogLevel.DEBUG)

Configuring logging verbosity

The application plug-in framework provides ways to specify what component loggers you would like to set
default verbosity for, such that you can easily turn logging on or off.
Server startup logging configuration
The server configuration file allows for specification of default log levels, as a top-level attribute
logLevel , which takes key-value pairs where the key is a regex pattern for component IDs, and the value
is an integer for the log levels.
For example:
For more information about the server configuration file, see Zowe Application Framework (zLUX)
configuration.

Using log message IDs

To make technical support for your application easier, create IDs for common log messages and use
substitution to generate them. When you use IDs, people fielding support calls can identify and solve
problems more quickly. IDs are particularly helpful if your application is translated, because it avoids users
having to explain problems using language that the tech support person might not understand.
To use log message IDs, take the following steps:
. Depending on how your application is structured, create message files in the following locations:
Web log messages: {plugin}/web/assets/i18n/log/messages_{language}.json
App server log messages: {plugin}/lib/assets/i18n/log/messages_{language}.json
. In the files, create ID-message pairs using the following format:
Where "id#" is the message ID and "value#" is the text. For example:
. Reference the IDs in your code, for example:
Which compiles to:
Or in another supported language, such as Russian:
Message ID logging examples
Server core: https://github.com/zowe/zlux-server-
framework/blob/v2.x/master/plugins/config/lib/assets/i18n/log/messages_en.json
Using Conda to make and manage packages
Version: v2.0.x LTS

of Application Framework Plugins

As Zowe is composed of components which can be extended by Plugins, a standardized and simple way to
find, install, upgrade, and list Plugins in your Zowe environment is important to make it easy to get the most
out of Zowe.
Package management as a concept generally provides a way to find packages such as plugins, check and
possible co-install dependencies the package has, and ultimately install the desired package. Post-install,
management tasks such as upgrading and uninstalling are common.
Conda is one such package manager, and if you are familiar with apt, yum, or npm, you will find that using
Conda is very similar. But, there are some important abilities that make Conda stand out:
Very cross platform: Conda is available, and acts very similar on z/OS, Windows, Linux, macOS, and
various Unix. Packages can state which platforms they support, so it easy to know what packages you
can install.
Tagging: On z/OS, Conda packages can contain tagging information, to avoid issues around the
difference between EBCDIC & ASCII.
Software neutrality: Language-specific package managers are becoming popular, but Conda does not
assume the purpose of the package, so you can install almost anything.
Environments: If desired, every user can have a different set of packages, because Conda can install &
manage packages in personal folders instead of system ones. A user can even have multiple such
environments, and switch between them rapidly to work with different sets of related software without
conflict.

Initial Conda setup

If you have not installed Conda yet, it can be downloaded as an all-in-one package that has no extra
dependencies, known as "miniconda". For Linux, Unix, macOS, and Windows, this can be downloaded at
https://docs.conda.io/en/latest/miniconda.html For z/OS, Conda can be downloaded from Rocket Software at
https://www.rocketsoftware.com/zos-open-source
Conda will prompt during the install for certain setup options, and ultimately you'll want to put some Conda
initialization content into your startup script so that whenever you open your terminal, Conda will be ready
for your use.
Once you have Conda downloaded and installed, you'll want to create your first Conda "environment" this
can be done by providing a path or a nickname
conda create --prefix PATH conda create --name ENVIRONMENT

Either will work, but path helps you better separate your content from content others use by placing it in a
folder that you can have stricter permissions on.
If you need to know more about certain commands, you can use the help command for any.
conda create --help

Or, check the official documentation: https://docs.conda.io/en/latest/index.html

Once you have an environment, you should activate it so that the actions you do are on that environment, as
opposed to the base one.
conda activate PATH_OR_NAME

Conda will detect whether the parameter is a path or a nickname, so this command works for both.
Finally, you can view the Conda environment and other information by checking "info"
conda info

Managing Conda channels

When downloading a package, such as a Zowe Plugin, the place that you download from is configurable.
These are called "Channels", but are very similar to "Repositories" seen in other package managers. With
Conda, you can install from:
A network channel (Internet or company internal)
A local channel (Collection of plugins on your computer)
Just an individual package, without a channel
You can have multiple of each, and if a package is present in more than one location, you can specify which
one to use.
Searching for packages
Conda has a search utility that searches for all Channels,
conda search anything_you_want

but it's important to note that because any type of software can be installed through Conda, you probably
want to search through a detailed view to help identify which ones are meant for Zowe, or use Channels that
are distinctly for Zowe so that you can get packages that are strictly for Zowe.
conda search --info anything_you_want

Using Conda with Zowe

Zowe is not yet available in the form of Conda packages yet, so it must be installed separately. If you have
Zowe installed on the same system as Conda, some Zowe Plugins installed through Conda will automatically
register into Zowe. In order to do this, the Plugins must be able to find Zowe. You should set environment
variables before trying to install the Plugins:
Setting environment variables temporarily:
z/OS, Linux, Unix:
Windows cmd.exe:
INSTANCE_DIR and ROOT_DIR are also supported, but the ZOWE_ prefix helps distinguish its purpose.

Setting environment variables persistently

z/OS, Linux, Unix: You can put the export statements into the .profile file in your home directory to
have them apply on login.
Windows: There is a UI to set variables, but it varies depending on Windows version. Try typing 'environment
variable' into the Windows search bar to get to the relevant menu.
Installing a Zowe plugin
A Conda package could contain one or more Zowe Plugins, and a Conda package could contain non-Zowe
code alongside Zowe Plugins. This is left up to the program vendor and regardless the install process is the
same:
conda install package_name

If the Zowe environment variables are set, such a package may automatically register Plugins into the Zowe
instance of your choice.
Zowe plugin configuration
Aside from possible automation during install and uninstall, Conda does not manage Zowe, its configuration,
or configuration of the Plugins. However, Conda does manage the package files, and therefore you can do
additional Zowe tasks on the Plugins by going into the Conda environment. Zowe Plugins are intended to be
found in a standardized location in the Conda environment,
/opt/zowe/plugins

This folder contains Plugins, which in turn contain sub-folders that are the Zowe components that they
utilize. If a plugin uses multiple Zowe components, its contents could be found within multiple component
folders.
/opt/zowe/plugins/my_plugin/app-server /opt/zowe/plugins/my_plugin/cli

Zowe package structure

Zowe Plugins packaged into Conda follow the structure outlined here: https://github.com/zowe/zowe-install-
packaging/issues/1569 This structure allows for plugin to have content meant for one or more Zowe
components. The Conda packages extend this by allowing for more than one Plugin, or a mix of Zowe
Plugins and other software to be within a single package.

Building Conda packages for Zowe

This document is intended to be provided with example scripts by the Zowe community, which shows you
how you can build a simple Zowe plugin into a Conda package. You can find the example scripts on the
Zowe zlux-build github repository. This is not intended to be a one-size-fits-all set of scripts. If you have
more advanced needs, you can use these scripts as a basis for writing your own scripts.
To make a Conda package, you need conda-build, which you can install into a Conda environment:
conda install conda-build
Once you have it, you can build a package via
conda build path/to/build/scripts

However, first you must set up the build information.

Defining package properties
Conda needs a metadata file, meta.yaml to state information about the package, such as dependencies,
what OS it supports, its name and version. This information can be programmatically found, and Zowe
provides examples of how to do this by reading Zowe's own metadata files into this one.
Creating build step
It's recommended not to build your code from scratch to put into Conda. Rather, build your code however
you want, and then just copy the contents into a Conda package. This keeps the Conda scripting small and
simple.
In the same folder as meta.yaml , Conda requires build.sh for building on Unix, Linux, or z/OS and
build.bat for Windows. Except for z/OS, this script does not determine where your package can be
used, it's just about where you are building it. z/OS is the exception because when you build on z/OS, unix
file tagging information is preserved. So, it's highly recommended that you tag your files so that users do not
have to deal with encoding issues. For code that works equally well on all platforms, a simple way to build for
all is:
. Build your code on Linux
. Transfer the output to z/OS
. Run a Conda build on the output on Linux
. Run a Conda build on the output on z/OS
. Deliver the Linux package as 'noarch' content, and the z/OS package as 'zos-z' content.
Lifecycle scripts
When a Conda package is installed or uninstalled, a script from the package can be run. For Zowe, the
scripts post-link.sh and pre-unlink.sh can be important, and you must put them into the same
folder as meta.yaml for building.
Install automation
post-link.sh runs at install, after Conda has put the package content onto the system. At this time,
registration into Zowe is recommended if the Plugin does not require any information from the user for
configuration. If the Plugin is okay to be automatically installed, we recommend putting a script into the
package folder named autoinstall.sh Zowe's provided Conda examples will utilize
autoinstall.sh to do any install steps your package needs, and provides Zowe information to make
install simple. However, it's possible to do what you want in your own post-link.sh script instead.
Uninstall automation
pre-unlink.sh is the opposite of post-link.sh . It allows you to do anything you need to before the
package is removed from the system. This is a good time to remove any package information from Zowe, but
you should be careful because users may uninstall and later re-install, so you should not remove
configuration information without consent.
Adding configuration to Conda packages
As a package manager, Conda is not responsible for configuration. Your packages can include defaults to
utilize, but if configuration is needed you should alert the user to perform a post-install task. post-
link.sh could be used to print such an alert.
Extending Zowe Explorer
Version: v2.0.x LTS

You can extend the possibilities of Zowe Explorer by creating you own extensions. For more information on
how to create your own Zowe Explorer extension, see Extensions for Zowe Explorer.
Developing for Zowe SDKs
Version: v2.0.x LTS

The Zowe SDKs are open source. You can contribute to add features, enhancements, and bug fixes to the
source code.
The functionality is currently limited to the interfaces provided by IBM z/OSMF. As a plug-in developer, you
can enhance the SDK by creating a packages that exposes programmatic APIs for your service.
For detailed contribution guidelines, see the following documents:
Node.js SDK guidelines
Coming soon! Python SDK guidelines
Zowe Conformance Program
Version: v2.0.x LTS

Introduction
Administered by the Open Mainframe Project, the Zowe™ Conformance Program aims to give users the
confidence that when they use a product, app, or distribution that leverages Zowe, they can expect a high
level of common functionality, interoperability, and user experience.
Conformance provides Independent Software Vendors (ISVs), System Integrators (SIs), and end users
greater confidence that their software will behave as expected. Just like Zowe, the Zowe Conformance
Program will continue to evolve and is being developed by committers and contributors in the Zowe
community.
As vendors, you are invited to submit conformance testing results for review and approval by the Open
Mainframe Project. If your company provides software based on Zowe, you are encouraged to get certified
today.

How to participate
To participate in the Zowe Conformance Program, follow the process on the Zowe Conformance Program
website. You can also find a list of products that have earned Zowe Conformant status.
To learn the criteria of achieving Zowe conformance for an offering, see Zowe Conformance Criteria.

How to suggest updates to the Zowe conformance

program
The Zowe conformance criteria is available as a table in a Markdown file in the Open Mainframe Project's
GitHub repo. If you find a mistake with the Zowe conformance documents, or you are a Zowe squad lead and
want to make an amendment to the criteria, you can update that Markdown file. The same information is also
held in another document Zowe Conformance Test Evaluation Guide that has history going back to Zowe
2019 conformance and allows easy change history comparison.
To submit a proposal to update the conformance criteria, fork the OMP's foundation repository at
https://github.com/openmainframeproject/foundation and make a pull request. Flag the Pull Request to the
attention of GitHub user ID @mertic , and also reach out to the Zowe onboarding squad in the #zowe-
onboarding Slack channel. If you are not already signed up to Zowe Slack community, you can sign up at
https://slack.openmainframeproject.org first.
Troubleshooting
Version: v2.0.x LTS

To isolate and resolve Zowe™ problems, you can use the troubleshooting and support information.

Known problems and solutions

Some common problems with Zowe are documented, along with their solutions or workarounds. If you have
a problem with Zowe installation and components, review the problem-solution topics to determine whether
a solution is available to the problem that you are experiencing.
You can also find error messages and codes, must-gathers, and information about how to get community
support in these topics.
Troubleshooting Zowe z/OS component installation
Troubleshooting API Mediation Layer
Troubleshooting Zowe Application Framework
Troubleshooting z/OS Services
Troubleshooting Zowe CLI
Troubleshooting Zowe Launcher

Collecting data for Zowe problems

Sometimes you cannot solve a problem by troubleshooting the symptoms. In such cases, you must collect
diagnostic data. To collect diagnostic data about Zowe, see Capturing diagnostics to assist problem
determination.

Verifying a Zowe release's integrity

Following a successful install of a Zowe release, the Zowe runtime directory should contain the code needed
to launch and run Zowe. If the contents of the Zowe runtime directory have been modified then this may
result in unpredictable behavior. To assist with this Zowe provides the ability to validate the integrity of a
Zowe runtime directory, see Verify Zowe runtime directory
Understanding the Zowe release
Knowing which version of Zowe you are running might help you isolate the problem. Also, the Zowe
community who helps you will need to know this information. For more information, see Understanding the
Zowe release.
Understanding the Zowe release
Version: v2.0.x LTS

Zowe releases
Zowe uses semantic versioning for its releases, also known as SemVer. Each release has a unique ID made
up of three numbers that are separated by periods.
Each time a new release is created, the release ID is incremented. Each number represents the content
change since the previous release. For example,
2.5.0 represents the fifth minor release since the first major release.

2.5.1 represents the first patch to the 2.5.0 release.

2.6.0 is the first minor release to be created after 2.5.1 .

Patch
A patch is usually reserved for a bug fix to a minor release.
Minor release
A minor release indicates that new functionality is added but the code is compatible with an earlier version.
The Zowe community works on two-week sprints and creates a minor release at the end of these, typically
once per month although the frequency might vary.
Major release
A major release is required if changes are made to the public API and the code is no longer compatible with
an earlier version.
When Zowe is version one, it is associated with the Zowe v1 conformance program. Offerings that extend
Zowe and achieve the Zowe v1 conformance badge will remain compatible with Zowe throughout its version
1 lifetime. A major release increment because of incompatibility is sometimes referred to as a "breaking"
change.
The first SMP/E build for Zowe v2 has a Functional Module ID (FMID) of AZWE002, which was created with
content from the 2.0.0 release. Each major release will be its own SMP/E FMID where the last digit is
updated, for example AZWE00V where V represents the major version.
Subsequent minor and patch releases to V2 are delivered as SMP/E PTF SYSMODs. Because of the size of
the content, two co-requisite PTFs are created for each Zowe release.
While Major releases are required for a "breaking" change, they also can be used to indicate to the
community a significant content update over and above what would be included in a minor release.

Check the Zowe release number

To see the release number of Zowe, look at the manifest.json file. This is included in the top-level
directory of where a Zowe convenience build is expanded to, the top-level directory of a Zowe runtime
<RUNTIME_DIR> .

To see the version of a Zowe release, use the zwe version command.
will return a single line with the Zowe release number. For example,
You can pass debug or trace mode argument to this command to show more information. For example,
You can see in trace mode, it also tells you where is the Zowe runtime directory where zwe command
you are running.
Verify Zowe runtime directory
Version: v2.0.x LTS

Zowe ships a zwe support verify-fingerprints command to help you verify authenticity of your
runtime directory. This command collects and calculates hashes for all files located in Zowe runtime
directory and compare the hashes shipped with Zowe. With this utility, you are able to tell what files are
modified, added, or deleted from original Zowe build.
Here is an example for successful verification:
If this verification fails, the script will exit with code 181 and display error messages like Number of
different files: 1 . You can optionally pass --debug or -v parameter to instruct this command to
verbosely display which files are different.
Troubleshooting Kubernetes environments
Version: v2.0.x LTS

The following topics contain information that can help you troubleshoot problems when you encounter
unexpected behavior installing and using Zowe™ containers in a Kubernetes environment.
ISSUE: Deployment and ReplicaSet failed to create pod
Problem:
If you are using OpenShift and see these error messages in ReplicaSet Events:
That means the Zowe ServiceAccount zowe-sa doesn't have any SecurityContextConstraint attached.
Solution:
You can run this command to grant a certain level of permission, for example, privileged , to zowe-sa
ServiceAccount:
ISSUE: Failed to create services
Problem:
If you are using OpenShift and apply services, you may see this error:
Solution:
To fix this issue, you can simply find and comment out this line in the Service definition files:
With OpenShift, you can define a PassThrough Route to let Zowe handle TLS connections.
Troubleshooting API ML
Version: v2.0.x LTS

As an API Mediation Layer user, you may encounter problems with how the API ML functions. This article
presents known API ML issues and their solutions.

Enable API ML Debug Mode

Use debug mode to activate the following functions:
Display additional debug messages for API ML
Enable changing log level for individual code components
Important: We highly recommend that you enable debug mode only when you want to troubleshoot issues.
Disable debug mode when you are not troubleshooting. Running in debug mode while operating API ML can
adversely affect its performance and create large log files that consume a large volume of disk space.
Follow these steps:
. Open the file zowe.yaml .
. For each component, find the components.*.debug parameter and set the value to true :
By default debug mode is disabled, so the components.*.debug is set to false .
. Restart Zowe™.
You enabled debug mode for the API ML core services (API Catalog, API Gateway and Discovery
Service).
. (Optional) Reproduce a bug that causes issues and review debug messages. If you are unable to
resolve the issue, create an issue here.

Change the Log Level of Individual Code Components

You can change the log level of a particular code component of the API ML internal service at run time.
Follow these steps:
. Enable API ML Debug Mode as described in Enable API ML Debug Mode. This activates the
application/loggers endpoints in each API ML internal service (Gateway, Discovery Service, and
Catalog).
. List the available loggers of a service by issuing the GET request for the given service URL:
scheme
Specifies the API ML service scheme (http or https)
hostname
Specifies the API ML service hostname
port
MFS_DS_PORT for the Discovery Service (by default, set to gateway port + 1), and MFS_AC_PORT
for the Catalog (by default, set to gateway port + 2).
Note: For the Catalog you can list the available loggers by issuing a GET request for the given service
URL in the following format:
Tip: One way to issue REST calls is to use the http command in the free HTTPie tool: https://httpie.org/.
Example:
. Alternatively, you extract the configuration of a specific logger using the extended GET request:
{name}
Specifies the logger name
. Change the log level of the given component of the API ML internal service. Use the POST request for
the given service URL:
The POST request requires a new log level parameter value that is provided in the request body:
level
Specifies the new log level: OFF, ERROR, WARN, INFO, DEBUG, TRACE
Example:
Known Issues
API ML stops accepting connections after z/OS TCP/IP stack is recycled
Symptom:
When z/OS TCP/IP stack is restarted, it is possible that the internal services of API Mediation Layer (Gateway,
Catalog, and Discovery Service) stop accepting all incoming connections, go into a continuous loop, and
write a numerous error messages in the log.
Sample message:
The following message is a typical error message displayed in STDOUT:
Solution:
Restart API Mediation Layer.
Tip: To prevent this issue from occurring, it is strongly recommended not to restart the TCP/IP stack while
API ML is running.
SEC0002 error when logging in to API Catalog
SEC0002 error typically appears when users fail to log in to API Catalog. The following image shows the API
Catalog login page with the SEC0002 error.

The error is caused by failed z/OSMF authentication. To determine the reason authentication failed, open the
ZWESVSTC joblog and look for a message that contains ZosmfAuthenticationProvider . The
following is an example of the message that contains ZosmfAuthenticationProvider :
Check the rest of the message, and identify the cause of the problem. The following list provides the
possible reasons and solutions for the z/OSMF authentication issue:
Connection refused
Missing z/OSMF host name in subject alternative names
Invalid z/OSMF host name in subject alternative names
Connection refused
In the following message, failure to connect to API Catalog occurs when connection is refused:
The reason for the refused connection message is either invalid z/OSMF configuration or z/OSMF being
unavailable. The preceding message indicates that z/OSMF is not on the 127.0.0.1 1443 interface.
Solution:
Configure z/OSMF
Make sure that z/OSMF is running and is on 127.0.0.1 1443 interface, and try to log in to API Catalog again. If
you get the same error message, change z/OSMF configuration.
Follow these steps:
. Locate the z/OSMF PARMLIB member IZUPRMxx.
For example, locate IZUPRM00 member in SYS1.PARMLIB.
. Change the current HOSTNAME configuration to HOSTNAME('*') .
. Change the current HTTP_SSL_PORT configuration to HTTP_SSL_PORT('1443') .
Important! If you change the port in the z/OSMF configuration file, all your applications lose connection
to z/OSMF.
For more information, see Syntax rules for IZUPRMxx.
If changing the z/OSMF configuration does not fix the issue, reconfigure Zowe.
Follow these steps:
. Open .zowe_profile in the home directory of the user who installed Zowe.
. Modify the value of the ZOWE_ZOSMF_PORT variable.
. Reinstall Zowe.
Missing z/OSMF host name in subject alternative names
In following message, failure to connect to API Catalog is caused by a missing z/OSMF host name in the
subject alternative names:
Solutions:
Fix the missing z/OSMF host name in subject alternative names using the following methods:
Note: Apply the insecure fix only if you use API Catalog for testing purposes.
Secure fix
Insecure fix
Secure fix
Follow these steps:
. Obtain a valid certificate for z/OSMF and place it in the z/OSMF keyring. For more information, see
Configure the z/OSMF Keyring and Certificate.
. Re-create the Zowe keystore by deleting it and re-creating it. For more information, see Configuring
Zowe certificates. The Zowe keystore directory is the value of the KEYSTORE_DIRECTORY variable in
the zowe.yaml file that is used to launch Zowe. See Creating and configuring the Zowe instance
directory for more information.
Insecure fix
Follow these steps:
. Re-create the Zowe keystore by deleting it and re-creating it. For more information, see Configuring
Zowe certificates. In the zowe-setup-certificates.env file that is used to generate the keystore,
ensure that the property VERIFY_CERTIFICATES and NONSTRICT_VERIFY_CERTIFICATES are
set to false .
Important! Disabling VERIFY_CERTIFICATES or NONSTRICT_VERIFY_CERTIFICATES may expose
your server to security risks. Ensure that you contact your system administrator before you do so and use
these options only for troubleshooting purpose.
Invalid z/OSMF host name in subject alternative names
In the following message, failure to connect to API Catalog is caused by an invalid z/OSMF host name in the
subject alternative names:
Solutions:
Fix the invalid z/OSMF host name in the subject alternative names using the following methods:
Request a new certificate
 Re-create the Zowe keystore
Request a new certificate
Request a new certificate that contains a valid z/OSMF host name in the subject alternative names.
Re-create the Zowe keystore
Re-create the Zowe keystore by deleting it and re-creating it. For more information, see Configuring Zowe
certificates. The Zowe keystore directory is the value of the KEYSTORE_DIRECTORY variable in the
zowe.yaml file that is used to launch Zowe. See Creating and configuring the Zowe instance directory.

API ML throws I/O error on GET request and cannot connect to other services
Symptom:
The API ML services are running but they are in DOWN state and not working properly. The following
exceptions can be found in the log: java.net.UnknownHostException and
java.net.NoRouteToHostException .

Sample message:
See the following message for full exceptions.
Solution:
The Zowe started task needs to run under the same user ID as z/OSMF (typically IZUSVR). This is stated in
the installation documentation.
The hostname that is displayed in the details of the exception is a valid hostname. You can validate that the
hostname is valid by using ping command on the same mainframe system. For example, ping
USILCA32.lvn.broadcom.net . If it is valid, then the problem can be caused by insufficient privileges of
your started task that is not allowed to do network access.
You can fix it by setting up the security environment as described in the Zowe documentation.
Certificate error when using both an external certificate and Single Sign-On to
deploy Zowe
Symptom:
You used an external certificate and Single Sign-On to deploy Zowe. When you log in to the Zowe Desktop,
you encounter an error similar to the following:
Solution:
This issue might occur when you use a Zowe version of 1.12.0 or later. To resolve the issue, you can
download your external root certificate and intermediate certificates in PEM format. Then, add the following
parameter in the zowe.yaml file.
environments.ZWED_node_https_certificateAuthorities:
"/path/to/zowe/keystore/local_ca/localca.cer-
ebcdic","/path/to/carootcert.pem","/path/to/caintermediatecert.pem"

Recycle your Zowe server. You should be able to log in to the Zowe Desktop successfully now.
Browser unable to connect due to a CIPHER error
Symptom:
When connecting to the API Mediation Layer, the web browser throws an error saying that the site is unable
to provide a secure connection because of an error with ciphers.
The error shown varies depending on the browser. For example,
For Google Chrome:

For Mozilla Firefox:

Solution:
Remove GCM as a disabled TLS algorithm from the Java runtime being used by Zowe.
To do this, first locate the $JAVA_HOME/lib/security/java.security file. You can find the value of
$JAVA_HOME in one of the following ways.

Method 1: By looking at the java.home value in the zowe.yaml file used to start Zowe.
 For example, if the zowe.yaml file contains the following line,
then, the $JAVA_HOME/lib/security/java.security file will be
/usr/lpp/java/J8.0_64/lib/security/java.security .

Method 2: By inspecting the STDOUT JES spool file for the ZWESVSTC started task that launches the
API Mediation Layer.
In the java.security file, there is a parameter value for jdk.tls.disabledAlgorithms , for
example,
Note: This line may have a continuation character \ and be split across two lines due to its length.
Edit the parameter value for jdk.tls.disabledAlgorithms to remove GCM . If as shown above the line
ends <224, GCM , remove the preceding comma so the values remain a well-formed list of comma-
separated algorithms:
Note: The file permissions of java.security might be restricted for privileged users at most z/OS sites.
After you remove GCM , restart the ZWESVSTC started task for the change to take effect.
API Components unable to handshake
Symptom:
The API Mediation Layer address spaces ZWE1AG, ZWE1AC and ZWE1AD start successfully and are visible
in SDSF, however they are unable to communicate with each other.
Externally the status of the API Gateway homepage will show ! icons against the API Catalog, Discovery
Service and Authentication Service (shown on the left side image below) which do not progress to green tick
icons as normally occurs during successful startup (shown on the right side image below).

The Zowe desktop is able to start but logon fails.

The log contains messages to indicate that connections are being reset. For example, the message below
shows that the API Gateway ZWEAG is unable to connect to the API Discovery service, by default 7553.
The Zowe desktop is able to be displayed in a browser but fails to logon.
Solution:
Check that the Zowe certificate has been configured as a client certificate, and not just as a server
certificate. More detail can be found in Configuring certificates.
Java z/OS components of Zowe unable to read certificates from keyring
Symptom:
Java z/OS components of Zowe are unable to read certificates from a keyring. This problem may appear as
an error as in teh following example where Java treats the SAF keyring as a file.
Example:
Solution:
Apply the following APAR to address this issue:
APAR IJ31756
Error Message Codes
Version: v2.0.x LTS

The following error message codes may appear on logs or API responses. Use the following message code
references and the corresponding reasons and actions to help troubleshoot issues.

API mediation utility messages

ZWEAM000I
%s started in %s seconds
Reason:
The service started.
Action:
No action required.

API mediation common messages

ZWEAO102E
Gateway not yet discovered. The Transform service cannot perform the request
Reason:
The Transform service was requested to transform a url, but the Gateway instance was not discovered.
Action:
Do not begin performing requests until the API Mediation Layer fully initializes after startup. Check that your
Discovery service is running and that all services (especially the Gateway) are discovered correctly.
ZWEAO104W
GatewayInstanceInitializer has been stopped due to exception: %s
Reason:
An unexpected exception occurred while retrieving the Gateway service instance from the Discovery
Service.
Action:
Check that both the service and the Gateway can register with Discovery. If the services are not registering,
investigate the reason why. If no cause can be determined, create an issue.
ZWEAO105W
Gateway HTTP Client per-route connection limit (maxConnectionsPerRoute) of %s has been reached for the
'%s' route.
Reason:
Too many concurrent connection requests were made to the same route.
Action:
Further connections will be queued until there is room in the connection pool. You may also increase the per-
route connection limit via the gateway start-up script by setting the Gateway configuration for
maxConnectionsPerRoute.
ZWEAO106W
Gateway HTTP Client total connection limit (maxTotalConnections) of %s has been reached.
Reason:
Too many concurrent connection requests were made.
Action:
Further connections will be queued until there is room in the connection pool. You may also increase the
total connection limit via the gateway start-up script by setting the Gateway configuration for
maxTotalConnections.
ZWEAO401E
Unknown error in HTTPS configuration: '%s'
Reason:
An Unknown error occurred while setting up an HTTP client during service initialization, followed by a system
exit.
Action:
Start the service again in debug mode to get a more descriptive message. This error indicates it is not a
configuration issue.

Common service core messages

ZWEAM100E
Could not read properties from: '%s'
Reason:
The Build Info properties file is empty or null.
Action:
The jar file is not packaged correctly. Please submit an issue.
ZWEAM101E
I/O Error reading properties from: '%s' Details: '%s'
Reason:
I/O error reading META-INF/build-info.properties or META-INF/git.properties .
Action:
The jar file is not packaged correctly. Please submit an issue.
ZWEAM102E
Internal error: Invalid message key '%s' is provided. Please create an issue with this message.
Reason:
Message service is requested to create a message with an invalid key.
Action:
Create an issue with this message.
ZWEAM103E
Internal error: Invalid message text format. Please create an issue with this message.
Reason:
Message service is requested to create a message with an invalid text format.
Action:
Create an issue with this message.
ZWEAM104E
The endpoint you are looking for '%s' could not be located
Reason:
The endpoint you are looking for could not be located.
Action:
Verify that the URL of the endpoint you are trying to reach is correct.
ZWEAM400E
Error initializing SSL Context: '%s'
Reason:
An error occurred while initializing the SSL Context.
Action:
Refer to the specific message to identify the exact problem. Possible causes include:
Incorrect security algorithm
The keystore is invalid or corrupted
The certificate is invalid or corrupted
ZWEAM500W
The service is not verifying the TLS/SSL certificates of the services
Reason:
This is a warning that the SSL Context will be created without verifying certificates.
Action:
Stop the service and set the verifySslCertificatesOfServices parameter to true , and then restart the
service. Do not use this option in a production environment.
ZWEAM501W
Service is connecting to Discovery service using the non-secure HTTP protocol.
Reason:
The service is connecting to the Discovery Service using the non-secure HTTP protocol.
Action:
For production use, start the Discovery Service in HTTPS mode and configure the services accordingly.
ZWEAM502E
Error reading secret key: '%s'
Reason:
A key with the specified alias cannot be loaded from the keystore.
Action:
Ensure that the configured key is present, in the correct format, and not corrupt.
ZWEAM503E
Error reading secret key: '%s'
Reason:
Error reading secret key.
Action:
Refer to the specific message to identify the exact problem. Possible causes include:
An incorrect security algorithm
The keystore is invalid or corrupted
The certificate is invalid or corrupted
ZWEAM504E
Error reading public key: '%s'
Reason:
Error reading secret key.
Action:
Refer to the specific message to identify the exact problem. Possible causes include:
An incorrect security algorithm
The keystore is invalid or corrupted
The certificate is invalid or corrupted
ZWEAM505E
Error initializing SSL/TLS context: '%s'
Reason:
Error initializing SSL/TLS context.
Action:
Refer to the specific message to identify the exact problem. Possible causes include:
An incorrect security algorithm
The keystore is invalid or corrupted
The certificate is invalid or corrupted
ZWEAM506E
Truststore Password configuration parameter is not defined
Reason:
Your truststore password was not set in the configuration.
Action:
Ensure that the parameter server.ssl.trustStorePassword contains the correct password for your truststore.
ZWEAM507E
Truststore configuration parameter is not defined but it is required
Reason:
The truststore usage is mandatory, but the truststore location is not provided.
Action:
If a truststore is required, define the truststore configuration parameter by editing the server.ssl.truststore,
server.ssl.truststorePassword and server.ssl.truststoreType parameters with valid data. If you do not require
a truststore, change the trustStoreRequired boolean parameter to false .
ZWEAM508E
Keystore not found, server.ssl.keyStore configuration parameter is not defined
Reason:
Your keystore path was not set in the configuration.
Action:
Ensure that the correct path to your keystore is contained in the parameter server.ssl.keyStore in the
properties or yaml file of your service.
ZWEAM509E
Keystore password not found, server.ssl.keyStorePassword configuration parameter is not defined
Reason:
Your keystore password was not set in the configuration.
Action:
Ensure that the correct password to your keystore in the parameter server.ssl.keyStorePassword is
contained in the properties or yaml file of your service.
ZWEAM510E
Invalid key alias '%s'
Reason:
The key alias was not found.
Action:
Ensure that the key alias provided for the key exists in the provided keystore.
ZWEAM511E
There was a TLS request error accessing the URL '%s': '%s'
Reason:
The Gateway refuses to communicate with the requested service.
Action:
Possible actions regarding to message content:
Message: The certificate is not trusted by the API Gateway. Action: Verify trust of the certificate is the
issue by disabling certificate verification and retry the request.
Message: Certificate does not match any of the subject alternative names. Action: Verify that the
hostname which the certificate is issued for matches the hostname of the service.
Message: Unable to find the valid certification path to the requested target. Action: Import the root CA
that issued services' certificate to API Gateway truststore.
Message: Verify the requested service supports TLS. Action: Ensure the requested service is running
with TLS enabled.
Message: Review the APIML debug log for more information. Action: Enable APIML debug mode and
retry the request, then review the APIML log for TLS errors.
ZWEAM600W
Invalid parameter in metadata: '%s'
Reason:
An invalid apiInfo parameter was found while parsing the service metadata.
Action:
Remove or fix the referenced metadata parameter.
ZWEAM700E
No response received within the allowed time: %s
Reason:
No response was received within the allowed time.
Action:
Verify that the URL you are trying to reach is correct and all services are running.
ZWEAM701E
The request to the URL '%s' has failed: %s caused by: %s
Reason:
The request failed because of an internal error.
Action:
Refer to specific exception details for troubleshooting. Create an issue with this message.

Security common messages

ZWEAT100E
Token is expired for URL '%s'
Reason:
The validity of the token is expired.
Action:
Obtain a new token by performing an authentication request.
ZWEAT103E
Could not write response: %s
Reason:
A message could not be written to the response.
Action:
Please submit an issue with this message.
ZWEAT403E
The user is not authorized to the target resource: %s
Reason:
The service has accepted the authentication of the user but the user does not have access rights to the
resource.
Action:
Contact your security administrator to give you access.
ZWEAT409E
The platform returned error: %s
Reason:
The platform responded with unknown errno code.
Action:
Please submit an issue with this message.
ZWEAT410E
The platform returned error: %s
Reason:
The specified password is incorrect.
Action:
Provide correct password.
ZWEAT411E
The platform returned error: %s
Reason:
The platform returned error, specified in the error message.
Action:
Contact your security administrator with the message.
ZWEAT412E
The platform returned error: %s
Reason:
The specified password is expired.
Action:
Contact your security administrator to reset your password.
ZWEAT413E
The platform returned error: %s
Reason:
The new password is not valid.
Action:
Provide valid password.
ZWEAT414E
The platform returned error: %s
Reason:
The user name access has been revoked.
Action:
Contact your security administrator to unsuspend your account.
ZWEAT415E
The platform returned error: %s
Reason:
The user name does not exist in the system.
Action:
Provide correct user name.
ZWEAT416E
The platform returned error: %s
Reason:
The specified user name or password is invalid.
Action:
Provide correct user name or password.
ZWEAT601E
z/OSMF service name not found. Set parameter apiml.security.auth.zosmf.serviceId to your service ID.
Reason:
The parameter zosmfserviceId was not configured correctly and could not be validated.
Action:
Ensure that the parameter apiml.security.auth.zosmf.serviceId is correctly entered with a valid z/OSMF
service ID.
ZWEAT602E
The SAF provider endpoint supports only the resource class 'ZOWE', but the current one is '%s'
Reason:
The parameter apiml.security.authorization.provider is set to endpoint
Action:
Change the SAF provider to another one to use this endpoint
ZWEAT603E
Endpoint %s is not properly configured
Reason:
The application cannot call the endpoint to check the SAF resource of the user
Action:
Verify the state of ZSS and IZS, then check if parameters
apiml.security.authorization.endpoint.* are matching.

ZWEAT604E
Passwords do not match
Reason:
Re-entered password does not match for password update.
Action:
Enter the same value as the one entered for new password.

Security client messages

ZWEAS100E
Authentication exception: '%s' for URL '%s'
Reason:
A generic failure occurred while authenticating.
Action:
Refer to the specific message to troubleshoot.
ZWEAS101E
Authentication method '%s' is not supported for URL '%s'
Reason:
The HTTP request method is not supported for the URL.
Action:
Use the correct HTTP request method that is supported for the URL.
ZWEAS103E
API Gateway Service is not available by URL '%s' (API Gateway is required because it provides the
authentication functionality)
Reason:
The security client cannot find a Gateway instance to perform authentication. The API Gateway is required
because it provides the authentication functionality.
Action:
Check that both the service and Gateway are correctly registered in the Discovery service. Allow some time
after the services are discovered for the information to propagate to individual services.
ZWEAS104E
Authentication service is not available by URL '%s'
Reason:
The Authentication service is not available.
Action:
Make sure that the Authentication service is running and is accessible by the URL provided in the message.
ZWEAS105E
Authentication is required for URL '%s'
Reason:
Authentication is required.
Action:
Provide valid authentication.
ZWEAS120E
Invalid username or password for URL '%s'
Reason:
The username or password is invalid.
Action:
Provide a valid username and password.
ZWEAS121E
Authorization header is missing, or the request body is missing or invalid for URL '%s'
Reason:
The authorization header is missing, or the request body is missing or invalid.
Action:
Provide valid authentication.
ZWEAS123E
Invalid token type in response from Authentication service.
Reason:
Could not retrieve the proper authentication token from the Authentication service response.
Action:
Review your APIML authentication provider configuration and ensure your Authentication service is working.
ZWEAS130E
Token is not valid for URL '%s'
Reason:
The token is not valid.
Action:
Provide a valid token.
ZWEAS131E
No authorization token provided for URL '%s'
Reason:
No authorization token is provided.
Action:
Provide a valid authorization token.

ZAAS client messages

ZWEAS100E
Token is expired for URL
Reason:
The application using the token kept it for longer than the expiration time
Action:
When this error occurs it is necessary to get a new JWT token.
ZWEAS120E
Invalid username or password
Reason:
Provided credentials weren't recognized
Action:
Try with different credentials
ZWEAS121E
Empty or null username or password values provided
Reason:
One of the credentials was null or empty
Action:
Try with full set of credentials
ZWEAS122E
Empty or null authorization header provided
Reason:
The authorization header was empty or null
Action:
Try again with a valid authorization header
ZWEAS170E
An exception occurred while trying to get the token
Reason:
General exception. There are more pieces of information in the message
Action:
Log the message from the exception and then handle the exception based on the information provided
there.
ZWEAS400E
Unable to generate PassTicket. Verify that the secured signon (PassTicket) function and application ID is
configured properly by referring to Using PassTickets in the guide for your security provider
Reason:
Unable to generate PassTicket.
Action:
Verify that the secured signon (PassTicket) function and application ID is configured properly by referring to
Using PassTickets in the guide for your security provider
ZWEAS401E
Token is not provided
Reason:
There was no JWT token provided for the generation of the PassTicket
Action:
Ensure that you are passing JWT token for PassTicker generation
ZWEAS404E
Gateway service is unavailable
Reason:
Gateway service does not respond.
Action:
Ensure that the Gateway service is up and that the path to the gateway service is properly set.
ZWEAS417E
The application name was not found
Reason:
The application id provided for the generation of the PassTicket was not recognized by the security provider
Action:
Ensure that the security provider recognized the application id.
ZWEAS130E
Invalid token provided
Reason:
The JWT token is not valid
Action:
Provide a valid token.
ZWEAS500E
There was no path to the trust store.
Reason:
The Zaas Client configuration does not contain the path to the trust store
Action:
Ensure that the configuration contains the trustStorePath and that it points to valid trust store.
ZWEAS501E
There was no path to the key store.
Reason:
The Zaas Client configuration does not contain the path to the key store
Action:
Ensure that the configuration contains the keyStorePath and that it points to valid key store.
ZWEAS502E
The configuration provided for SSL is invalid.
Reason:
The type of the keystore, truststore or the included keys/certs aren't considered valid
Action:
Ensure that the combination of the configuration is cryptographically valid.
ZWEAS503E
The SSL configuration contained invalid path.
Reason:
There was an invalid path to either trust store or keystore
Action:
Ensure that both provided paths are resolved to valid trust store and valid key store

Discovery service messages

ZWEAD400E
Cannot notify Gateway on '%s' about new instance '%s'
Reason:
The Discovery Service tried to notify the Gateway about an instance update, but the REST call failed. The
purpose of this call is to update the Gateway caches. The Gateway might be down or a network problem
occurred.
Action:
Ensure that there are no network issues and that the Gateway was not restarted. If the problem reoccurs,
contact Broadcom support.
ZWEAD401E
Cannot notify Gateway on '%s' about cancelled registration
Reason:
The Discovery Service tried to notify the Gateway about service un-registration, but the REST call failed. The
purpose of this call is to update the Gateway caches. The Gateway might be down or a network problem
occurred.
Action:
Ensure that there are no network issues and that the Gateway was not restarted. If the problem reoccurs,
contact Broadcom support.
ZWEAD700W
Static API definition directory '%s' is not a directory or does not exist
Reason:
One of the specified static API definition directories does not exist or is not a directory.
Action:
Review the static API definition directories and their setup. The static definition directories are specified as a
launch parameter to a Discovery service jar. The property key is:
apiml.discovery.staticApiDefinitionsDirectories

ZWEAD701E
Error loading static API definition file '%s'
Reason:
A problem occurred while reading (IO operation) of a specific static API definition file.
Action:
Ensure that the file data is not corrupted or incorrectly encoded.
ZWEAD702W
Unable to process static API definition data: '%s' - '%s'
Reason:
A problem occurred while parsing a static API definition file.
Action:
Review the mentioned static API definition file for errors. Refer to the specific log message to determine the
exact cause of the problem:
ServiceId is not defined in the file '%s'. The instance will not be created. Make sure to specify the
ServiceId.
The instanceBaseUrls parameter of %s is not defined. The instance will not be created. Make sure
to specify the InstanceBaseUrl property.
The API Catalog UI tile ID %s is invalid. The service %s will not have an API Catalog UI tile. Specify the
correct catalog title ID.
 One of the instanceBaseUrl of %s is not defined. The instance will not be created. Make sure to specify
the InstanceBaseUrl property.
The URL %s does not contain a hostname. The instance of %s will not be created. The specified URL is
malformed. Make sure to specify valid URL.
The URL %s does not contain a port number. The instance of %s will not be created.
The specified URL is missing a port number. Make sure to specify a valid URL.
The URL %s is malformed. The instance of %s will not be created: The Specified URL is malformed.
Make sure to specify a valid URL.
The hostname of URL %s is unknown. The instance of %s will not be created: The specified hostname
of the URL is invalid. Make sure to specify a valid hostname.
Invalid protocol. The specified protocol of the URL is invalid. Make sure to specify valid protocol.
Additional service metadata of %s in processing file %s could not be created: %s
ZWEAD703E
A problem occurred during reading the static API definition directory: '%s'
Reason:
There are three possible causes of this error:
The specified static API definition folder is empty.
The definition does not denote a directory.
An I/O error occurred while attempting to read the static API definition directory.
Action:
Review the static API definition directory definition and its contents on the storage. The static definition
directories are specified as a parameter to launch a Discovery Service jar. The property key is:
apiml.discovery.staticApiDefinitionsDirectories

ZWEAD704E
Gateway Service is not available so it cannot be notified about changes in Discovery Service
Reason:
Gateway Service is probably mis-configured or failed to start from another reason.
Action:
Review the log of Gateway Service and its configuration.

Gateway service messages

ZWEAG500E
Client certificate is missing in request.
Reason:
No client certificate is present in the HTTPS request.
Action:
Properly configure client to send client certificate.
ZWEAG700E
No instance of the service '%s' found. Routing will not be available.
Reason:
The Gateway could not find an instance of the service from the Discovery Service.
Action:
Check that the service was successfully registered to the Discovery Service and wait for Spring Cloud to
refresh the routes definitions.
ZWEAG701E
Service '%s' does not allow encoded characters in the request path: '%s'.
Reason:
The request that was issued to the Gateway contains an encoded character in the URL path. The service
that the request was addressing does not allow this pattern.
Action:
Contact the system administrator and request enablement of encoded characters in the service.
ZWEAG702E
Gateway does not allow encoded slashes in request: '%s'.
Reason:
The request that was issued to the Gateway contains an encoded slash in the URL path. Gateway
configuration does not allow this encoding in the URL.
Action:
Contact the system administrator and request enablement of encoded slashes in the Gateway.
ZWEAG704E
Configuration error '%s' when trying to read the public and private key for signing JWT: %s
Reason:
A problem occurred while trying to read the certificate-key pair from the keystore.
Action:
Review the mandatory fields used in the configuration such as the keystore location path, the keystore and
key password, and the keystore type.
ZWEAG705E
Failed to load public or private key from key with alias '%s' in the keystore '%s'. Gateway is shutting down.
Reason:
Failed to load a public or private key from the keystore during JWT Token initialization.
Action:
Check that the key alias is specified and correct. Verify that the keys are present in the keystore.
ZWEAG706E
RequestContext is not prepared for load balancing.
Reason:
Custom Ribbon load balancing is not in place before calling Ribbon.
Action:
Contact Broadcom support.
ZWEAG707E
The request to the URL '%s' aborted without retrying on another instance. Caused by: %s
Reason:
The request to the server instance failed and will not be retried on another instance.
Action:
Refer to 'Caused by' details for troubleshooting.
ZWEAG708E
The request to the URL '%s' failed after retrying on all known service instances. Caused by: %s
Reason:
Request to the server instance could not be executed on any known service instance.
Action:
Verify the status of the requested instance.
ZWEAG709E
Service is not available at URL '%s'. Error returned: '%s'
Reason:
The service is not available.
Action:
Make sure that the service is running and is accessible by the URL provided in the message.
ZWEAG710E
Load balancer does not have available server for client: %s
Reason:
The service is not available. It might be removed by the Circuit Breaker or by requesting specific instance
that is not available.
Action:
Try the request later, or remove the request for the specific instance.
ZWEAG711E
The principal '%s' is missing queried authorization.
Reason:
The principal does not have the queried access to the resource name within the resource class.
Action:
No action is needed.
ZWEAG712E
The URI '%s' is an invalid format
Reason:
The URI does not follow the format /{serviceId}/{type}/{version}/{endpoint} or
/{type}/{version}/{serviceId}/{endpoint}.
Action:
Use a properly formatted URI.
ZWEAG713E
Configuration error when trying to establish JWT producer. Events: %s
Reason:
A problem occurred while trying to make sure that there is a valid JWT producer available.
Action:
Based on the specific information in the message, verify that the key configuration is correct, or alternatively,
that z/OSMF is available.
ZWEAG714E
Unknown error occurred while retrieving the used public key
Reason:
An unknown problem occured when retrieving the used public key. This should never occur.
Action:
Try again later.
ZWEAG715E
The wrong amount of keys retrieved. The amount of retrieved keys is: %s
Reason:
There are too many keys in the JWK set. As such, it is not possible to choose the correct one.
Action:
Verify the configuration of the z/OSMF to make sure that z/OSMF provides only one used key.
ZWEAG716E
The system does not know what key should be used.
Reason:
Typically z/OSMF is either unavailable or offline.
Action:
Verify that z/OSMF is available, accessible by the Gateway service, and online.
ZWEAG100E
Authentication exception: '%s' for URL '%s'
Reason:
A generic failure occurred during authentication.
Action:
Refer to the specific authentication exception details for troubleshooting.
ZWEAG101E
Authentication method '%s' is not supported for URL '%s'
Reason:
The HTTP request method is not supported by the URL.
Action:
Use the correct HTTP request method supported by the URL.
ZWEAG102E
Token is not valid
Reason:
The JWT token is not valid.
Action:
Provide a valid token.
ZWEAG103E
The token has expired
Reason:
The JWT token has expired.
Action:
Obtain a new token by performing an authentication request.
ZWEAG104E
Authentication service is not available at URL '%s'. Error returned: '%s'
Reason:
The authentication service is not available.
Action:
Make sure that the authentication service is running and is accessible by the URL provided in the message.
ZWEAG105E
Authentication is required for URL '%s'
Reason:
Authentication is required.
Action:
Provide valid authentication.
ZWEAG106W
Login endpoint is running in dummy mode. Use credentials '%s'/'%s' to log in. Do not use this option in the
production environment.
Reason:
The authentication is running in dummy mode.
Action:
Ensure that this option is not being used in a production environment.
ZWEAG107W
Incorrect value: apiml.security.auth.provider = '%s'. The authentication provider is not set correctly. The
default 'zosmf' authentication provider is being used.
Reason:
An incorrect value of the apiml.security.auth.provider parameter is set in the configuration.
Action:
Ensure that the value of apiml.security.auth.provider is set either to 'dummy' if you want to use dummy
mode, or to 'zosmf' if you want to use the z/OSMF authentication provider.
ZWEAG108E
z/OSMF instance '%s' not found or incorrectly configured. Gateway is shutting down.
Reason:
The Gateway could not find the z/OSMF instance from the Discovery Service or it could not communicate
with the provided z/OSMF instance.
Action:
Ensure that the z/OSMF instance is configured correctly and that it is successfully registered to the
Discovery Service and that the API Mediation Layer can communicate with the provided z/OSMF instance.
The default timeout is 5 minutes. On a slower system, add the variable
components.gateway.apiml.security.jwtInitializerTimeout:... and the value in minutes into Zowe's
configuration to override this value.
ZWEAG109E
z/OSMF response does not contain field '%s'.
Reason:
The z/OSMF domain cannot be read.
Action:
Review the z/OSMF domain value contained in the response received from the 'zosmf/info' REST endpoint.
ZWEAG110E
Error parsing z/OSMF response. Error returned: '%s
Reason:
An error occurred while parsing the z/OSMF JSON response.
Action:
Check the JSON response received from the 'zosmf/info' REST endpoint.
ZWEAG120E
Invalid username or password for URL '%s'
Reason:
The username and/or password are invalid.
Action:
Provide a valid username and password.
ZWEAG121E
Authorization header is missing, or the request body is missing or invalid for URL '%s'
Reason:
The authorization header is missing, or the request body is missing or invalid.
Action:
Provide valid authentication.
ZWEAS123E
Invalid token type in response from Authentication service.
Reason:
Could not retrieve the proper authentication token from the Authentication service response.
Action:
Review your APIML authentication provider configuration and ensure your Authentication service is working.
ZWEAG130E
Token is not valid for URL '%s'
Reason:
The token is not valid.
Action:
Provide a valid token.
ZWEAG131E
No authorization token provided for URL '%s'
Reason:
No authorization token is provided.
Action:
Provide a valid authorization token.
ZWEAG140E
The 'applicationName' parameter name is missing.
Reason:
The application name is not provided.
Action:
Provide the 'applicationName' parameter.
ZWEAG141E
The generation of the PassTicket failed. Reason: %s
Reason:
An error occurred in the SAF Auth Service. Review the reason in the error message.
Action:
Supply a valid user and application name, and check that corresponding permissions have been set up.
ZWEAG150E
SAF IDT generation failed. Reason: %s
Reason:
An error occurred during SAF verification. Review the reason in the error message.
Action:
Verify the Identity Token configuration.
ZWEAG151E
SAF IDT is not generated because authentication or authorization failed. Reason: %s
Reason:
The user credentials were rejected during SAF verification. Review the reason in the error message.
Action:
Provide a valid username and password.

API Catalog messages

ZWEAC100W
Could not retrieve all service info from discovery -- %s -- %s -- %s
Reason:
The response from The Discovery Service about the registered instances returned an error or empty body.
Action:
Make sure the Discovery Service is up and running. If the http response error code refers to a security issue,
check that both the Discovery Service and Catalog are running with the https scheme and that security is
configured properly.
ZWEAC101E
Could not parse service info from discovery -- %s
Reason:
The response from the Discovery Service about the registered instances could not be parsed to extract
applications.
Action:
Run debug mode and look at the Discovery Service potential issues while creating a response. If the
Discovery Service does not indicate any error, create an issue.
ZWEAC102E
Could not retrieve containers. Status: %s
Reason:
One or more containers could not be retrieved.
Action:
Check the status of the message for more information and the health of the Discovery Service.
ZWEAC103E
API Documentation not retrieved, %s
Reason:
API documentation was not found.
Action:
Make sure the service documentation is configured correctly.
ZWEAC104E
Could not retrieve container statuses, %s
Reason:
The status of one or more containers could not be retrieved.
Action:
Check the status of the message for more information and the health of the Discovery Service.
ZWEAC700E
Failed to update cache with discovered services: '%s'
Reason:
Cache could not be updated.
Action:
Check the status of the Discovery Service.
ZWEAC701W
API Catalog Instance not retrieved from Discovery service
Reason:
An error occurred while fetching containers information.
Action:
The jar file is not packaged correctly. Please submit an issue.
ZWEAC702E
An unexpected exception occurred when trying to retrieve an API Catalog instance from the Discovery
Service: %s
Reason:
An unexpected error occurred during API Catalog initialization. The API Catalog was trying to locate an
instance of itself in the Discovery Service.
Action:
Review the specific message for more information. Verify if the Discovery Service and service registration
work as expected.
ZWEAC703E
Failed to initialize API Catalog with discovered services
Reason:
The API Catalog could not initialize running services after several retries.
Action:
Ensure services are started and discovered properly.
ZWEAC704E
ApiDoc retrieval problem for '%s' service. %s
Reason:
ApiDoc for service could not be retrieved.
Action:
Verify that the service provides a valid ApiDoc.
ZWEAC705W
The home page url for service %s was not transformed. %s
Reason:
The home page url for service was not transformed. The original url will be used.
Action:
Refer to the specific printed message. Possible causes include:
The Gateway was not found. The Transform service cannot perform the request. Wait for the Gateway
to be discovered.
The URI is not valid. Ensure the service is providing a valid URL.
Not able to select a route for the URL of the specific service. The original URL is used. If necessary,
check the routing metadata of the service.
The path of the service URL is not valid. Ensure the service is providing the correct path.
ZWEAC706E
Service not located, %s
Reason:
The service could not be found.
Action:
Check if the service is up and registered. If it is not registered, review the onboarding guide to ensure that all
steps were completed.
ZWEAC707E
Static API refresh failed, caused by exception: %s
Reason:
The Static API refresh could not be performed because of exception.
Action:
Check the specific exception for troubleshooting.
ZWEAC708E
The API base path for service %s was not retrieved. %s
Reason:
The API base path for service was not retrieved. An empty path will be used.
Action:
Refer to the specific printed message. Possible causes include:
The URI is not valid. Ensure the service is providing a valid URL.
Not able to select a route for the URL of the specific service. The original URL is used. If necessary,
check the routing metadata of the service.
The path of the service URL is not valid. Ensure the service is providing the correct path.
ZWEAC709E
Static definition generation failed, caused by exception: %s
Reason:
The Static definition generation could not be performed because of exception.
Action:
Check the specific exception for troubleshooting.
Raising a Zowe Application Framework issue
Version: v2.0.x LTS

on GitHub
When necessary, you can raise GitHub issues against the Zowe™ zlux core repository here. It is suggested
that you use either the bug or enhancement template.
For issues with particular applications, such as Code Editor or JES Explorer, create the issue in the
application's project.

Raising a bug report

Please provide as much of the information listed on Troubleshooting Zowe Application Framework as
possible. Anyone working on the issue might need to request this and other information if it is not supplied
initially. A description of the error and how it can be reproduced is the most important information.

Raising an enhancement report

Enhancement reports are just as important to the Zowe project as bug reports. Enhancement reports should
be clear and detailed requirements for a potential enhancement.
ZSS Error Message Codes
Version: v2.0.x LTS

The following error message codes may appear on ZSS log. Use the following message code references and
the corresponding reasons and actions to help troubleshoot issues.

ZSS informational messages

ZWES0013I
ZSS Server has started. Version '%s' '%s'
Reason:
ZSS Server has started.
Action:
No action required.
ZWES0014I
ZIS status - '%s' (name='%.16s', cmsRC='%d', description='%s', clientVersion='%d')
Reason:
The message shows status of the connection to Privileged Server: ZIS status - <OK or Failure>
(name= <Privileged Server Name> , cmsRC= <RC> , description= <description , clientVersion=
<version> )

Action:
if Status is OK then no action required. If Status is Failure see check <cmsRC> and description. In the
cases listed below check that the ZWESISTC started task is running. If not, start it with the TSO command
/S ZWESISTC :

cmsRC=12 , description= 'Global area address is NULL'

cmsRC=39 , description= 'Cross-memory server abended'

 cmsRC=47 , description= 'ZVT is NULL'
cmsRC=64 , description= 'PC is unavailable'

ZWES0035I
ZSS Server settings: Address='%s', port='%d', protocol='%s'
Reason:
Server is starting using Address= <IP address> , port= <port> , protocol= http or https
Action:
No action required.
ZWES0039I
Installing '%s' service...
Reason:
<Service> is about to install.

Action:
No action required.
ZWES0061I
TLS settings: keyring '%s', label '%s', password '%s', stash '%s'
Reason:
ZSS uses TLS settings: keyring <keyring> or <p12-file> , label <cert-label> , password
"****" or (no password) , stash <stash-file> or (no stash) .

Action:
No action required.
ZWES0063I
Caching Service settings: gateway host '%s', port %d
Reason:
Caching Service settings are gateway host <Gateway-host> , port <Gateway-port> . HA is mode
enabled.
Action:
No action required.
ZWES0064I
Caching Service not configured
Reason:
Caching Service not configured. HA mode is disabled.
Action:
No action required.
ZWES1100I
Product Registration is enabled.
Reason:
Product Registration is enabled.
Action:
No action required.
ZWES1101I
Product Registration is disabled.
Reason:
Product Registration is disabled.
Action:
No action required.
ZWES1102I
Product Registration successful.
Reason:
Product Registration successful.
Action:
No action required.
ZWES1600I
JWT will be configured using JWK URL '%s'
Reason:
JWT will be configured using JSON Web Key(JWK) at URL <url> .
Action:
No action required.
ZWES1601I
Server is ready to accept JWT with (or without ) fallback to legacy tokens
Reason:
Server is ready to accept JWT with or without fallback to legacy tokens.
Action:
No action required.

ZSS error messages

ZWES1006E
Error while parsing plugin definition file '%s': '%s'.
Reason:
An error occurred while parsing <plugin-definition-file> : <error-details> .
Action:
If you are a plugin developer check <error-details> and fix the error by editing <plugin-
definition-file> , otherwise, report the error to the plugin vendor.

ZWES1034E
Server startup problem: Address '%s' not valid.
Reason:
IP address nor hostname is not valid.
Action:
Use valid IP address or hostname, e.g. 0.0.0.0 .
ZWES1036E
Server startup problem: Ret='%d', res='0x%x'
Reason:
Server has failed to start.
Action:
If the next message is ZWES1037E then refer ZWES1037E. Otherwise, examine the reason code with
bpxmtext command, e.g. use bpxmtext 744c7247 if you got res='0x744c7247'

ZWES1037E
This is usually because the server port '%d' is occupied. Is ZSS running twice?
Reason:
ZSS port number is already occupped.
Action:
Check if another ZSS instance is already running, or chose another free port number and restart Zowe.
ZWES1065E
Failed to configure https server, check agent https settings
Reason:
Failed to configure https server.
Action:
Check agent https settings.

ZSS warning messages

ZWES1000W
Privileged server name not provided, falling back to default.
Reason:
Privileged server name not defined in configuration file.
Action:
If your privileged server name is ZWESIS_STD then no action required. Otherwise set
components.zss.crossMemoryServerName property in configuration to the correct name.

ZWES1005W
Plugin ID was not found in '%s'
Reason:
pluginId property wasn't found in <path-to-pluginDefinition.json> file. The plugin skipped.

Action:
If you are a plugin developer add pluginId property into <path-to-pluginDefinition.json> file.
Otherwise, contact the plugin vendor.
ZWES1012W
Could not open pluginsDir '%s': Ret='%d', res='0x%x'
Reason:
Could not open <pluginsDir> : Ret= <return-code> , res= <reason-code>
Action:
Check that <pluginsDir> exists and allows reading. Examine the reason code with bpxmtext
command for additional information.
ZWES1060W
Failed to init TLS environment, rc=%d(%s)
Reason:
Failed to initialized TLS environment GSKit return code <rc> ( <description> )
Action:
Ensure that ZSS certificate is configured correctly. Check GSKit return code and description for additional
information.
ZWES1103W
Product Registration failed, RC = %d
Reason:
Failed to register ZSS.
Action:
Examine the return code at [https://www.ibm.com/docs/en/zos/2.2.0?topic=requeststatus-return-codes] and
correct the error.
ZWES1201W
Could not %s file '%s': Ret='%d', res='%d'
Reason:
Unixfile REST Service could not <action> file <filename> : Ret= <return-code> , res= <reason-
code>

Action:
Action depends on return/reason code. For additional information examine the reason code with
bpxmtext command.

ZWES1103W
Could not get metadata for file '%s': Ret='%d', res='%d'
Reason:
Unixfile REST Service could not get metadata for file <filename> : Ret= <return-code> , res=
<reason-code>

Action:
Action depends on return/reason code. For additional information examine the reason code with
bpxmtext command.

ZWES1602W
JWK is in unrecognized format
Reason:
JSON Web Key(JWK) is in unrecognized format.
Action:
Report an issue at [https://github.com/zowe/zlux/issues]
ZWES1603W
Failed to construct public key using JWK
Reason:
JSON Web Key(JWK) has invalid public key info.
Action:
Report an issue at [https://github.com/zowe/zlux/issues]
ZWES1604W
JWK: failed to init HTTP context, ensure that APIML and TLS settings are correct
Reason:
Failed to init HTTP context for requesting JSON Web Key(JWK).
Action:
Check the zowe keystore configuration and specification of it within the zowe server config.
ZWES1605W
Server will not accept JWT
Reason:
ZSS Server will not accept JWT.
Action:
No action required.
ZWES1606W
Failed to get JWK - %s, retry in %d seconds
Reason:
Failed to get JWK - <reason> , retry in <n> seconds. ZSS Server was unable to get JSON Web
Key(JWK), it will try to repeat the attempt in <n> seconds.
Action:
No action required.
Troubleshooting Zowe CLI
Version: v2.0.x LTS

Problem
Zowe™ CLI is experiencing a problem. You need to collect information that will help you resolve the issue.
Environment
These instructions apply to Zowe CLI installed on Windows, Mac OS X, and Linux systems as a standalone
installation via a Zowe download or an NPM registry.

Before reaching out for support

. Is there already a GitHub issue (open or closed) that covers the problem? Check CLI Issues.
. Review the current list of Known issues in documentation. Also try searching using the Zowe Docs
search bar.

Resolving the problem

Collect the following information to help diagnose the issue:
Zowe CLI version installed.
List of plug-ins installed and their version numbers.
Node.js and NPM versions installed.
List of environment variables in use.
For instructions on how to collect the information, see Gathering information for Zowe CLI.
The following information is also useful to collect:
If you are experiencing HTTP errors, see z/OSMF troubleshooting for information to collect.
Is the CLI part of another Node application, such as VSCode, or is it a general installation?
What operating system and version are you running?
What shell/terminal are you using (bash, cmd, powershell, etc...)?
Which queue managers are you trying to administer, and on what systems are they located?
Are the relevant API endpoints online and valid?
Are you running in daemon mode?
Gathering information to troubleshoot Zowe
Version: v2.0.x LTS

CLI
Follow these instructions to gather specific pieces of information to help troubleshoot Zowe™ CLI issues.

Identify the currently installed CLI version

Issue the following command:
The exact Zowe CLI version may vary depending upon if the @latest or @zowe-v1-lts , or @lts-
incremental version is installed.

For the @zowe-v1-lts and the @latest (forward-development) version tags:

For the @lts-incremental version tag:
More information regarding versioning conventions for Zowe CLI and plug-ins is located in Versioning
Guidelines.

Identify the currently installed versions of plug-ins

Issue the following command:
The output describes version and the registry information.

Environment variables
The following settings are configurable via environment variables:
Log levels
Environment variables are available to specify logging level and the CLI home directory.
Important! Setting the log level to TRACE or ALL might result in "sensitive" data being logged. For example,
command line arguments will be logged when TRACE is set.
For more information about logging and environment variables, see Setting CLI log levels.
CLI daemon mode
By default, the CLI daemon mode binary creates or reuses a file in the user's home directory each time a
Zowe CLI command runs. In some cases, this behavior might be undesirable. For example, the home
directory resides on a network drive and has poor file performance. For information about how to change the
location that the daemon uses, see Setting CLI daemon mode properties.
Home directory
You can set the location on your computer for the Zowe CLI home directory, which contains log files,
profiles, and plug-ins for the product.
The default .zowe folder is created when you issue your first Zowe CLI command. If you change the
location of the folder, you must reinstall plug-ins and recreate or move profiles and log files that you want to
retain. In some cases, you might want to maintain a different set of profiles in multiple folders, then switch
between them using the environment variable.
For information about setting an environment variable for the Zowe CLI home directory, see Setting the CLI
home directory.
The values for these variables can be echoed.

Home directory structure

Location of logs
There are two sets of logs to be aware of:
Imperative CLI Framework log, which generally contains installation and configuration information.
Zowe CLI log, which contains information about interaction between CLI and the server endpoints.
Analyze these logs for any information relevant to your issue.
Profile configuration
The profiles folder stores connection information.
Important! The profile directory might contain "sensitive" information, such as your mainframe password.
You should obfuscate any sensitive references before providing configuration files.

Node.js and npm

Zowe CLI is compatible with the currently supported Node.js LTS versions. For an up-to-date list of
supported LTS versions, see Node.js.org.
To gather the Node.js and npm versions installed on your computer, issue the following commands:
npm configuration
If you are having trouble installing Zowe CLI from an npm registry, gather your npm configuration to help
identify issues with registry settings, global install paths, proxy settings, etc...
npm log files
In case of errors, npm creates log files in the npm_cache\_logs location. To get the npm_cache
location for a specific OS, run the following command:
By default, npm keeps only 10 log files, but sometimes more are needed. Increase the log count by issuing
the following command:
This command increases the log count to 50, so that more log files will be stored on the system. Now you
can run tests multiple times and not lose the log files. The logs can be passed to Support for analysis.
As the log files are created only when an npm command fails, but you are interested to see what is executed,
you can increase the log level of npm. Issue the following command:
With this change, you can see all actions taken by npm on the stdout. If the command is successful, it
still does not generate a log file.
The available log levels are: "silent", "error", "warn", "notice", "http", "timing", "info", "verbose", "silly",
and "notice". "Notice" is the default.
Alternatively, you can pass --loglevel verbose on the command line, but this only works with
npm related commands. By setting log level in the config, it also works when you issue some zowe
commands that use npm (for example, zowe plugins install @zowe/cics ).
z/OSMF troubleshooting
Version: v2.0.x LTS

The core command groups use the z/OSMF REST APIs which can experience any number of problems.
If you encounter HTTP 500 errors with the CLI, consider gathering the following information:
. The IZU* (IZUSVR and IZUANG) joblogs (z/OSMF server)
. z/OSMF USS logs (default location: /global/zosmf/data/logs - but may change depending on installation)
If you encounter HTTP 401 errors with the CLI, consider gathering the following information:
. Any security violations for the TSO user in SYSLOG

Alternative methods
At times, it may be beneficial to test z/OSMF outside of the CLI. You can use the CLI tool curl or a REST
tool such as "Postman" to isolate areas where the problem might be occurring (CLI configuration, server-
side, etc.).
Example curl command to GET /zosmf/info :
Known Zowe CLI issues
Version: v2.0.x LTS

The following topics contain information that can help you troubleshoot problems when you encounter
unexpected behavior installing and using Zowe™ CLI.

EACCESS error when issing npm install command

Valid on Windows, Mac, or Linux
Symptom:
An EACCESS error is returned when you issue the npm install -g command to install a package from
Zowe.org or npm.
Solution:
To resolve the issue, follow the steps described in Resolving EACCESS permissions errors when installing
packages globally in the npm documentation.

Command not found message displays when issuing npm

install commands
Valid on all supported platforms
Symptom:
When you issue NPM commands to install the CLI, the message command not found displays. The message
indicates that Node.js and NPM are not installed on your computer, or that PATH does not contain the
correct path to the NodeJS folder.
Solution:
To correct this behavior, verify the following:
Node.js and NPM are installed.
PATH contains the correct path to the NodeJS folder.
More Information: System requirements for Zowe CLI

npm install -g Command Fails Due to an EPERM Error

Valid on Windows
Symptom:
This behavior is due to a problem with Node Package Manager (npm). There is an open issue on the npm
GitHub repository to fix the defect.
Solution:
If you encounter this problem, some users report that repeatedly attempting to install Zowe CLI yields
success. Some users also report success using the following workarounds:
Issue the npm cache clean command.
Uninstall and reinstall Zowe CLI. For more information, see Install Zowe CLI.
Add the --no-optional flag to the end of the npm install command.

Sudo syntax required to complete some installations

Valid on Linux and macOS
Symptom:
The installation fails on Linux or macOS.
Solution:
Depending on how you configured Node.js on Linux or macOS, you might need to add the prefix sudo
before the npm install -g command or the npm uninstall -g command. This step gives Node.js
write access to the installation directory.

npm install -g command fails due to

npm ERR! Cannot
read property 'pause' of undefined error
Valid on Windows or Linux
Symptom:
You receive the error message npm ERR! Cannot read property 'pause' of undefined when
you attempt to install the product.
Solution:
This behavior is due to a problem with Node Package Manager (npm). If you encounter this problem, revert
to a previous version of npm that does not contain this defect. To revert to a previous version of npm, issue
the following command:

Node.js commands do not respond as expected

Valid on Windows or Linux
Symptom:
You attempt to issue node.js commands and you do not receive the expected output.
Solution:
There might be a program that is named node on your path. The Node.js installer automatically adds a
program that is named node to your path. When there are pre-existing programs that are named node on
your computer, the program that appears first in the path is used. To correct this behavior, change the order
of the programs in the path so that Node.js appears first.

Installation fails on Oracle Linux 6

Valid on Oracle Linux 6
Symptom:
You receive error messages when you attempt to install the product on an Oracle Linux 6 operating system.
Solution:
Install the product on Oracle Linux 7 or another Linux or Windows OS. Zowe CLI is not compatible with
Oracle Linux 6.
Raising a CLI issue on GitHub
Version: v2.0.x LTS

When necessary, you can raise GitHub issues against the Zowe™ CLI repository here. It is suggested that
you use either the bug or enhancement template.

Raising a bug report

Please provide as much of the information listed on Troubleshooting CLI as is reasonable. Anyone working
on the issue might need to request this and other information if it is not supplied initially. A description of the
error and how it can be reproduced is the most important information.

Raising an enhancement report

Enhancement reports are just as important to the Zowe project as bug reports. Enhancement reports should
be clear and detailed requirements for a potential enhancement.
Troubleshooting Zowe Explorer
Version: v2.0.x LTS

As a Zowe Explorer user, you may encounter problems with how the VS Code extension functions. This
article presents known Zowe Explorer issues and their solutions.

Before reaching out for support

. Is there already a GitHub issue (open or closed) that covers the problem? Check Zowe Explorer Issues.
. Review the current list of Known issues in documentation. Also, try searching using the Zowe Docs
search bar.
. Collect the following information to help diagnose the issue:
Zowe Explorer and VS Code version installed.
Node.js and NPM versions installed.
Whether you have Zowe CLI and the Secure Credential Store (SCS) Zowe CLI plug-in installed.
Note: Zowe CLI V2 does not require the SCS plug-in to manage security. Security is now managed
by Zowe CLI core functionality.
Your operating system.
Zowe Logs, which usually, can be found in C:\Users\userID\.zowe\zowe\logs .
Use the Slack channel to reach the Zowe Explorer community for assistance.
Known Zowe Explorer issues
Version: v2.0.x LTS

The following topics contain information that can help you troubleshoot problems when you encounter
unexpected behavior, using Zowe Explorer.

Data Set Creation Error

Symptom:
Data set creation fails.
Sample message:
Error running command zowe.createDataset: z/OSMF REST API Error: http(s) request error event called
Error: self signed certificate in certificate chain. This is likely caused by the extension that contributes
zowe.createDataset.
Solution:
Set the value of the Reject-Unauthorized parameter to false . Use the profile edit function to change
profile's parameters.

Opening Binary Files Error

Symptom:
When opening a binary file, an error message appears.
Sample messages:
Solution:
There is no solution or workaround at this time.
Raising a Zowe Explorer issue on GitHub
Version: v2.0.x LTS

You can raise GitHub issues against the Zowe Explorer repository. It is suggested that you use either the bug
or feature request.

Raising a bug report

Please provide as much of the information listed on Troubleshooting Zowe Explorer as is reasonable. Anyone
working on the issue might need to request this and other information if it is not supplied initially. A
description of the error and how it can be reproduced is the most important information.

Submitting a feature request

Feature requests are just as important to the Zowe project as bug reports. Feature requests should contain
clearly formulated ideas that can improve user experience.
Troubleshooting Zowe Launcher
Version: v2.0.x LTS

The following topics contain information that can help you troubleshoot problems when you encounter
unexpected behavior using Zowe™ Launcher.
Issues and development of the Zowe Launcher is managed in GitHub. When you troubleshoot a problem,
you can check whether a GitHub issue (open or closed) that covers the problem already exists. For a list of
issues, see the launcher repo.
Error Message Codes

Enable Zowe Launcher Debug Mode

Use debug mode to display additional debug messages for Zowe Launcher.
Important: We highly recommend that you enable debug mode only when you want to troubleshoot issues.
Disable debug mode when you are not troubleshooting. Running Zowe Launcher in debug mode can
adversely affect its performance and consume a large amount of spool space.
Follow these steps:
. Open the PROCLIB member ZWESLSTC
. Find STDENV DD inline statements
. Add a new line
By default debug mode is disabled, so the ZLDEBUG is set to OFF . To disable debug mode remove
the line or set ZLDEBUG to OFF .
. Restart ZWESLSTC Started Task.
Error Message Codes
Version: v2.0.x LTS

The following error message codes may appear on Zowe Launcher SYSPRINT. Use the following message
code references and the corresponding reasons and actions to help troubleshoot issues.

Zowe Launcher informational messages

ZWEL0001I
component %s started
Reason:
Component <component-name> started.
Action:
No action required.
ZWEL0002I
component %s stopped
Reason:
Component <component-name> stopped.
Action:
No action required.
ZWEL0003I
new component initialized %s, restart_cnt=%d, min_uptime=%d seconds, share_as=%s
Reason:
Component <component-name> initialized.
 restart_cnt - Number of attempts to restart the component in case of failure
min_uptime - Minimum uptime that the component can be considered as successfully started

share_as - One of <yes|no|must> which indicates whether child processes of the component
start in the same address space. See documentation for _BPX_SHAREAS for details.
Action:
No action required.
ZWEL0004I
component %s(%d) terminated, status = %d
Reason:
Component <component-name> ( <pid> ) terminated with status <code> .
Action:
No action required.
ZWEL0005I
next attempt to restart component %s in %d seconds
Reason:
Component failure detected.
Action:
No action required. The component <component-name> will be restarted in <n> seconds.

Zowe Launcher error messages

ZWEL0030E
failed to prepare Zowe instance
Reason:
Failed to prepare the Zowe high availability (HA) instance.
Action:
Check previous messages in the Zowe Launcher SYSPRINT to find the reason and correct it.
ZWEL0038E
failed to restart component %s, max retries reached
Reason:
Maximum retries reached for restarting component <component-name >.
Action:
Check <component-name> configuration and correct the maximum restart count via configuration
attribute restartIntervals if needed, then restart the component by using z/OS MODIFY command F
ZWESLSTC,APPL=STOP(<component-name>)

ZWEL0040E
failed to start component %s
Reason:
Failed to start component <component-name> .
Action:
Check <component-name> configuration and correct if needed, then either 1) start the component
manually by using z/OS MODIFY command F ZWESLSTC,APPL=STOP(<component-name>) or 2) restart
the entire HA instance
Contribute to Zowe
Version: v2.0.x LTS

You are welcome to contribute to Zowe in many forms and help make this project better! We want to make it
as easy as possible for you to become a Zowe contributor. This topic outlines the different ways that you can
get involved and provides some of the resources that are available to help you get started. All feedback is
welcome.
Report bugs and enhancements
Fix issues
Send a Pull Request
Report security issues
Contribution guidelines
Promote Zowe
Helpful resources

Report bugs and enhancements

Report bugs: Download and try one of the latest Zowe builds. Report any bugs you find by creating a
Zowe bug report in GitHub.
Report enhancements: Got an idea for a feature? Or something you're already using could be improved?
Post an enhancement request in GitHub!
If you have an issue that is specific to a sub-project or community team, feel free to submit an issue against
a specific repo.

Fix issues
There are many issues and bugs with the label Good first issue in the Zowe GitHub repositories
to help you get familiar with the contribution process. Check out the following list of GitHub repos to
make your contribution!
Zowe sub-projects repositories
Zowe operations squads repositories
 When you decide to work on an issue, check the comments on that issue to ensure that it's not taken by
anyone. If nobody is working on it, comment on that issue to let others know that you want to work on it
to avoid duplicate work. The squad can assign that issue to you and provide guidance as well.
You can also reach out to the Zowe squads on Slack to check with the squads if there is any good
starter issue that you can work on.

Send a Pull Request

All code in Zowe aligns with the established licensing and copyright notice guidelines.
Before submitting a Pull Request, review the general Zowe Pull Request Guidelines and make sure that you
provide the information that is required in the Pull Request template in that specific repo.
All Zowe commits need to be signed by using the Developerʼs Certificate of Origin 1.1 (DCO), which is the
same mechanism that the Linux® Kernel and many other communities use to manage code contributions.
You need to add a Signed-off-by line as a part of the commit message. Here is an example Signed-
off-by line, which indicates that the submitter accepts the DCO:

Signed-off-by: John Doe <john.doe@hisdomain.com>

You can find more information about DCO signoff in the zac repo.

Report security issues

Please direct all security issues to zowe-security@lists.openmainframeproject.org . A member of
the security team will reply to acknowledge receipt of the vulnerability and coordinate remediation with the
affected project.

Contribution guidelines
Check out the contribution guidelines for different components and squads to learn how to participate.
Zowe CLI
Zowe API Mediation Layer
Zowe Application Framework
Zowe Explorer
 Zowe Client SDKs
Zowe Docs

Promote Zowe
Contribute a blog about Zowe. Read the Zowe blog guidelines to get started.
Present Zowe on conferences and social channels

Helpful resources
General code guidelines
UI guidelines
Zowe learning resources
Code categories
Version: v2.0.x LTS

The Zowe™ codebase consists of a few key areas, with both unique and shared guidelines that define how
to write new code. A few such areas are:
Server Core
Server Security
Microservices
Zowe Desktop Applications
Zowe Application Framework
Zowe CLI and CLI Plug-ins
Imperative CLI Framework

Programming languages
For each area of the codebase, there are established and favored programming languages. Each repository
in Github identifies the primary language used. Some of the basic skills needed to contribute to the project
include:
CLI - Node.js, TypeScript
Desktop UI - Node.js, JavaScript
APIs - C, Assembler, Java, Spring
API Mediation Layer - Java, Spring
Note: JavaScript is not recommended and should be avoided in favor of Typescript to utilize typing.

Component-specific guidelines and tutorials

This "Code Guidelines" section provides high-level best practices. Each component may have more specific
contribution guidelines. Look for a CONTRIBUTING.md file in the component's GitHub repository for specific
details.
To learn more about how to develop Zowe applications and plug-ins or extending Zowe with APIs, see
Extending.
General code style guidelines
Version: v2.0.x LTS

All code written in the languages described in Code categories should adhere to the following guidelines to
facilitate collaboration and understanding.
Note: Uncertainties, unimplemented but known future action-items, and odd/specific constants should all
be accompanied with a short comment to make others aware of the reasoning that went into the code.

Whitespaces
Do not use tabs for whitespace. Use 2 spaces per tab instead.

Naming Conventions
Self-documenting code reduces the need for extended code comments. It is encouraged to use names as
long as necessary to describe what is occurring.
Functions and methods
Methods should be named as verbs (for example, get or set ), while Objects/Classes should be nouns.
Objects and functions should be CamelCase. Methods on Objects should be dromedaryCase.
Variables
Constants should be CAPITALIZED_AND_UNDERSCORED for clarity, while variables can remain
dromedaryCase.
Avoid non-descriptive variable names such as single letters (except for iteration in loops such as i or j) and
variable names that have been arbitrarily shortened (Don't strip vowels; long variable names are OK).
Pull requests guidelines
Version: v2.0.x LTS

The Zowe™ source code is stored in GitHub repositories under the Zowe GitHub project. You contribute to
the project through Pull Requests in GitHub.
Each pull request is made against a repository that has assigned "maintainers". Pull requests cannot be
merged without the approval of at least one maintainer, who will review Pull Requests to ensure that they
meet the following criteria:
The code in the pull request must adhere to the General Code Style Guidelines.
The code must compile/transpile (where applicable) and pass a smoke-test such that the code is not
known to break the current state of Zowe.
The pull request must describe the purpose and implementation to the extent that the maintainer
understands what is being accomplished. Some pull requests need less details than others.
The pull request must state how to test this change, if applicable, such that the maintainer or a QA team
can check correctness. The explanation may simply be to run included test code.
If a pull request depends upon a pull request from the same/another repository that is pending, this
must be stated such that maintainers know in which order to merge open pull requests.
Documentation Guidelines
Version: v2.0.x LTS

Documentation of Zowe™ comes in various forms depending on the subject being detailed. In general,
consider how you can help end users and contributors through external documentation, in-product help,
error messages, etc... and open an issue in zowe/docs-site if you need assistance.

Contributing to external documentation

The external documentation for the Zowe project, Zowe Docs, is completely open-source. See How to
contribute for more information about contributing to the documentation.
Consider: Release Notes, Install/Config/User Guides, Developer Tutorials, etc...

Component Categories
Provide the following documentation depending on the component that you contribute to:
Server Core
Principles of operation and end-user guides (configuration, troubleshooting) should be documented on
Zowe Docs site. Code documentation follows language-specific formats.
Server Security
Principles of operation and end-user guides (configuration, troubleshooting) should be documented on
Zowe Docs site. Code documentation follows language-specific formats.
Microservices
Microservices implement a web API, and therefore must be documented for understanding and testing.
These web APIs must be accompanied with documentation in the Swagger (https://swagger.io/) format.
These documents must be Swagger 2.0, .yaml extension files. Zowe Application Framework plug-ins that
implement microservices should store these files within the /doc/swagger folder.
Zowe Desktop Applications
Zowe Desktop applications should include documentation that explains how to use them, such that this
documentation can integrate with a Zowe Desktop documentation reader. This is not strictly API
documentation, but rather user guides that can display within the Desktop GUI. The preferred
documentation format is a .md extension file that exists in the /doc/guide folder of an App.
Web Framework
Principles of operation and end-user guides (configuration, troubleshooting) should be documented on
Zowe Docs site. Code documentation follows language-specific formats.
CLI Plugins
Provide a readme.md file for developers (overview, build, test) as well as end-user documentation for your
plug-in on Zowe Docs site.
For more information, see the CLI documentation contribution guidelines.
Core CLI Imperative CLI Framework
Contributions that affect end users of the CLI should be documented on Zowe Docs site.
Contributions that affect the underlying Imperative CLI Framework should be documented in the GitHub Wiki
for future developers using the framework.
Code documentation follows language-specific formats.

Programming Languages
Each of the common languages in Zowe have code-documentation-generation tools, each with their own in-
code comment style requirements to adhere to in order to generate readable API references. Objects and
functions of interest should be commented in accordance to the language-specific tools to result in output
that serves as the first point of documentation for APIs.
Typescript
When writing TypeScript code, comment objects and functions in compliance with JSDoc. If you are writing
in an area of the codebase that does not yet have a definition file for JSDoc, define a configuration file that
can be used for future documentation of that code.
Java
When writing TypeScript code, comment objects and functions in the Javadoc format.
C
When writing C code, comment functions and structures in compliance with Doxygen.
Introduction
Version: v2.0.x LTS

This style guide is the visual language that represents Zowe™. It is a living document that will be updated
based on the needs of our users and software requirements.

Clear
Our users rely on our software to help them be efficient in their work. The interfaces and experiences that
we design should be clear so that there is never confusion about where to click or how to take the next step.
Users should always feel confident in their actions.

Consistent
Users should be able to look at Zowe software products and know that they are in a family. Each software
product is different, but should use similar patterns, icons, and interactions. If a user switches to a new
product within Zowe, it should feel familiar.

Smart
Our users are intelligent, and they need smart software. Zowe design patterns should always compliment
the userʼs intelligence and reflect the userʼs complex work environment. Designs should align with the Zowe
design language by putting the human needs of the user first.
Colors
Version: v2.0.x LTS

Color brings a design to life. Color is versatile; it's used to express emotion and tone, as well as place
emphasis and create associations. Color should always be used in meaningful and intentional ways to create
patterns and visual cues.

Color palette
The Zowe™ color palette is designed and implemented in a theme-able manner. The universal color
variables are determined by common roles and usage; it is not based singularly on a color value (i.e. unique
hex code). The same color value might be assigned to multiple variables in a theme's palette when the
values have distinctly different roles.
A universal variable can also have multiple associated roles when the color is consistently used across those
roles. This allows for uniform color application across themes, while giving each theme the freedom to
express its own individuality at a more detailed level.

Light theme

Dark theme

Color contrast | WCAG AA standards

Type colors
All type color combinations on Zowe must pass WCAG AA standards of 4.5 1 for normal text and 3 1 for
large text. For larger text, if the font weight is light (300) or normal (400) the text should be no smaller
than 24px. If the font weight is Semi-Bold (600) then the large text should be no smaller than 19px.
Body Text (4.5 1)
 Large Text (3 1): at least 24px / 19px semi-bold
WCAG guidelines: https://www.w3.org/WAI/standards-guidelines/wcag/
Contrast Checker Tool: https://webaim.org/resources/contrastchecker/
Typography
Version: v2.0.x LTS

Typography is used to create clear hierarchies, useful organizations, and purposeful alignments that guide
users through the product and experience. It is the core structure of any well designed interface.

Typeface
Title typeface: Roboto Condensed
Body typeface: Roboto
Sample:

Font weight
Font weight is an important typographic style that can add emphasis and is used to differentiate content
hierarchy. Font weight and size pairings must be carefully balanced. A bold weight will always have more
emphasis than a lighter weight font of the same size. However, a lighter weight font can rank hierarchically
higher than a bold font if the lighter weight type size is significantly larger than the bold.
Roboto font family provides a wide range of weights. However, only SemiBold, Regular, Light should be used
for product design.
Font-weight: 300 / Light

Should only be used at sizes greater than or equal to 18px / 1.125rem

Font-weight: 400 / Normal
 Font-weight: 500 / Semi-bold

Body copy
We recommended that you use two sizes for body copy. The first size is UI specific. To maximize screen real
estate we chose a smaller 14px / 0.875rem body copy size for the standard UI console. However, for areas
that have prolonged reading, such as Documentation, we use a larger body copy size of 16px / 1rem to
enhance readability.

Line scale
1.333 Perfect Fourth-type scale - desktop

1.2 Minor Third type-scale - mobile

Line-height
Line-height, traditionally known as leading, is one of several factors that directly contribute to readability and
pacing of copy. Line-heights are based on the size of the font itself. Ideal line-heights for standard copy have
a ratio of 1 1.5 (typesize : line-height). For example, a type at 16px / 1rem would have a line-height of 1.5rem /
24px (16 x 1.5). The exception to this rule are headings, which need less spacing and therefore have a line-
height ratio of 1 1.25.

Embed font
To embed your selected fonts into a web page, copy the following code into the <head> of your HTML
document:

Import font
Specify in CSS
Use the following CSS rules to specify these families:
Grid
Version: v2.0.x LTS

Grid systems are used for creating page layouts through a series of rows and columns that house your
content. Zowe™ uses a responsive, mobile-first, fluid grid system that appropriately scales up to 12 columns
as the device or view port size increases.

12 column grid
A 12 column grid is recommended. 12 is a well-distributed division that provides a good range of widths to
assign to content. It is dividable by 2, 3, 4 and 6, which allows flexibility. Many frameworks, such as
Bootstrap and Pure, use a 12 column grid by default. Other grid systems like a 5 column grid can reduce
flexibility, balance, and consistency.

Gutters
Columns create gutters (gaps between column content) through padding. For devices with a screen width
greater than 768px, the column padding is 20px. For devices with a screen width less than 768px, the
column padding is 10px.
Screen width ≥ 768px = 20px gutters
Screen width 768px = 10px gutters

Columns
Zowe designs should be limited to 12 columns. If designers feel that they need fewer columns in their grid,
they can specify the number of 12 available columns they wish to span.
This can translate to percentages of the twelve columns. Using this method, a designer can create a folded,
less granular grid. For example, if your component spans three equal columns, that is equal to 25% of twelve
columns.
Column count: 12
Margins
The 12 column grid does not have a maximum width. It has a width of 100%, with built in margins that create
padding between column count and the edges of the viewport.
In devices with a screen width greater than 768px, the margins are 5% on the left, and 5% on the right.
In devices with a screen width less than 768px, the margins are 3% on the left, and 3% on the right.
Example: Screen Width > 768px

Example: Screen Width 320px

Iconography
Version: v2.0.x LTS

Icons are key component for a successful UI design because they are a visual way to help add meaning to
elements.
Font Awesome is a robust icon library that allows for an easy addition to any web project. Scalable vector
icons that can instantly be customized — size, color, drop shadow, and anything that can be done with the
power of CSS.

One Font, Hundreds of Icons – In a single collection, Font Awesome is a pictographic language of
web-related actions.
No JavaScript Required – Fewer compatibility concerns because Font Awesome doesnʼt require
JavaScript.
Infinite Scalability – Scalable vector graphics means every icon looks awesome at any size.
Free, as in Speech – Font Awesome is completely free for commercial use. Check out the license.
CSS Control – Easily style icon color, size, shadow, and anything thatʼs possible with CSS.
Perfect on Retina Displays – Font Awesome icons are vectors, which mean theyʼre gorgeous on high-
resolution displays.
Plays Well with Others – Originally designed for Bootstrap, Font Awesome works great with all
frameworks.
Desktop Friendly – To use on the desktop or for a complete set of vectors, check out the cheatsheet.
Accessibility-minded – Font Awesome loves screen readers and helps make your icons accessible on
the web.
To learn more or download the library go to www.fontawesome.com
Application icon
Version: v2.0.x LTS

General rules
Embrace simplicity. Use a simple, unique shape or element that represents the essence of the application.
Avoid excessive details and redundant shading.
Use the Zowe™ color palette. Avoid using a monochromatic palette for your icons. Use the Zowe color
palette to ensure that the icons have a consistent look.
Use unique shapes and design elements. Avoid using single commonly used design elements, such as
the gear, document, or folder. These elements can reduce recognizability. Do not use photos and
screenshots. Keep icons simple and abstract.
Avoid labels and text. Short, commonly used abbreviations are acceptable, if necessary. Remember that all
icons have center-aligned labels beneath them.
Use brand identity. If your Zowe application has a brand identity element such as a logo, you can use it.
Remember to include the copyright symbol.

Shape, size, and composition

Use a flat design style. Flat design focuses on open space, bright colors, and flat graphics or illustrations.
Our minimalistic design approach puts the emphasis on usability.

A flat icon has clean, crisp edges and a flat dimensional layout.
Use solid fill shapes. Most Zowe App icons have solid fill shapes, which are more readable on dark
backgrounds.
Use the circle shape for the background application icons. Set the outer corners to 100% opacity. Create an
image file that is 87x87 pixels, and save the file in PNG format.
Maintain consistent visual proportions.
Colors and shades
Verify the contrast
Verify that the background color of the icon provides enough contrast against the desktop.

Use the Zowe palette

To ensure that your app icons are clear and consistent, use the Zowe color palette. If you need to use well-
established brand identity elements, you can use the colors that are associated with the brand.
Layer Shadows
Use smooth shadows to represent that some elements are on different layers and should be visually
separated. Avoid using too many layers because they can overcomplicate the icon.

Use the long shadow for consistency.

Although the long shadow effect does not have any semantic meaning, it adds focus to the main icon shape
and identifies the central,most meaningful element.
Use the gradient shadow settings shown in the following image, or use a flat non-gradient shadow with 20%
opacity and #000000 color.
Contributing to Zowe Documentation
Version: v2.0.x LTS

You are welcome to contribute to the Zowe™ documentation repository. Anyone can open an issue about
documentation, or contribute a change with a pull request (PR) to the zowe/docs-site GitHub repository.

Before You Get Started

Before contributing a documentation change to the repository, you should be familiar with:
Git and GitHub: To learn about git and GitHub, refer to the Github Guides.
Slack: The Zowe Documentation team communicates using the Slack application. To learn about Slack,
refer to the Slack Help Center. The Zowe team is part of the Open Mainframe Project channel.
Markdown Language: The Zowe documentation is written in Markdown language. To learn about
Markdown, refer to The Markdown Guide.
In addition to being familiar with the Zowe community and how we work together, you will need to sign the
CNCF Contributor License Agreement. The Contributor License Agreement defines the terms under which
you contribute to Zowe documentation. Contributions to Zowe documentation are reviewed before being
committed to the repository. Committing changes to the Zowe repository requires additional access rights.
See https://github.com/zowe/community/blob/master/COMMITTERS.md. Also see Participating in Zowe
Documentation for more details about roles and permissions.

Getting started checklist

If you are ready to get started contributing to the Zowe Documentation repository:
Verify that you are familiar with the concepts in Before You Get Started.
Familiarize yourself with the Zowe documentation repository.
Verify that you can open a pull request and review changes.
Open an issue for Zowe documentation if you find a problem.
Read the documentation style guide.

The Zowe documentation repository

The Zowe documentation is managed in a GitHub repository.
Review the site's overall organization and structure
Review the help files related to your planned changes or addition

Sending a GitHub Pull Request

You can provide suggested edit to any documentation page by using the Edit this page link on top of each
page. After you make the changes, you submit updates in a pull request for the Zowe documentation team
to review and merge.
Follow these steps:
. Click Edit this page on the page that you want to update.
. Make the changes to the file.
. Scroll to the end of the page and enter a brief description about your change.
. Optional: Enter an extended description.
. Select Propose file change.
. Select Create pull request.

Opening an issue for Zowe documentation

You can request the documentation to be improved or clarified, report an error, or submit suggestions and
ideas by opening an issue in GitHub for the Zowe documentation team to address. The team tracks the
issues and works to address your feedback.
Follow these steps:
. Click the Open doc issue link at the top of the page.
. Enter the details of the issue.
. Click Submit new issue.

Documentation style guide

This section gives writing style guidelines for the Zowe documentation.
 Headings and titles
Technical elements
Tone
Word usage
Graphics
Abbreviations
Structure and format
Headings and titles
Use sentence-style capitalization for headings
Capitalize only the initial letter of the first word in the text and other words that require capitalization, such as
proper nouns. Examples of proper nouns include the names of specific people, places, companies,
languages, protocols, and products.
Example: Verifying that your system meets the software requirements.
For tasks and procedures, use gerunds for headings.
Example:
Building an API response
Setting the active build configuration
For conceptual and reference information, use noun phrases for headings.
Example:
Query language
Platform and application integration
Use headline-style capitalization for only these items:
Titles of books, CDs, videos, and stand-alone information units.
Example:
Installation and User's Guide
 Quick Start Guides or discrete sets of product documentation
Technical elements
Variables
Style:
Italic when used outside of code examples,
Example: myHost
If wrap using angle brackets <> within code examples, italic font is not supported.
Example:
put <pax-file-name>.pax
Where pax-file-name is a variable that indicates the full name of the PAX file you download. For
example, zoe-0.8.1.pax.
Message text and prompts to the user
Style: Put messages in quotation marks.
Example: "The file does not exist."
Code and code examples
Style: Monospace
Example: java -version
Command names, and names of macros, programs, and utilities that you can type as commands
Style: Monospace
Example: Use the BROWSE command.
Interface controls
Categories: check boxes, containers, fields, folders, icons, items inside list boxes, labels (such as Note:),
links, list boxes, menu choices, menu names, multicolumn lists, property sheets, push buttons, radio
buttons, spin buttons, and Tabs
Style: Bold
Example: From the Language menu, click the language that you want to use. The default selection is
English.
Directory names
Style: Monospace
Example: Move the install.exe file into the newuser directory.
File names, file extensions, and script names
Style: Monospace
Example:
Run the install.exe file.
Extract all the data from the .zip file.
Search or query terms
Style: Monospace
Example: In the Search field, enter Zowe .
Citations that are not links
Categories: Chapter titles and section titles, entries within a blog, references to industry standards, and topic
titles in IBM Knowledge Center
Style: Double quotation marks
Example:
See the "Measuring the true performance of a cloud" entry in the blog.
For installation information, see "Installing the product".
Tone
Use simple present tense rather than future or past tense, as much as possible.
Example:
✔ The API returns a promise.
❌ The API will return a promise.
Use simple past tense if past tense is needed.
Example:
✔ The limit was exceeded.
❌ The limit has been exceeded.
Use active voice as much as possible
Example:
✔ In the Limits window, specify the minimum and maximum values.
❌ The Limits window is used to specify the minimum and maximum values.
Exceptions: Passive voice is acceptable when any of these conditions are true:
The system performs the action.
It is more appropriate to focus on the receiver of the action.
You want to avoid blaming the user for an error, such as in an error message.
The information is clearer in passive voice.
Example:
✔ The file was deleted.
❌ You deleted the file.
Using second person such as "you" instead of first person such as "we" and "our".
In most cases, use second person ("you") to speak directly to the reader.
End sentences with prepositions selectively
Use a preposition at the end of a sentence to avoid an awkward or stilted construction.
Example:
✔ Click the item that you want to search for.
❌ Click the item for which you want to search.
Avoid anthropomorphism
Focus technical information on users and their actions, not on a product and its actions.
Example:
✔ User focus: On the Replicator page, you can synchronize your local database with replica databases.
❌ Product focus: The Replicator page lets you synchronize your local database with replica databases.
Avoid complex sentences that overuse punctuation such as commas and semicolons.
Word usage
Note headings such as Note, Important, and Tip should be formatted using the lower case and bold
format.
Example:
Note:
Important!
Tip:
Use of "following"
For whatever list or steps we are introducing, the word "following" should precede a noun.
Example:
Before a procedure, use "Follow these steps:"
 The <component_name> supports the following use cases:
Before you install Zowe, review the following prerequisite installation tasks:
Avoid ending the sentence with "following".
Example:
❌ Complete the following.
✔ Complete the following tasks.
Use a consistent style for referring to version numbers.
When talking about a specific version, capitalize the first letter of Version.
Example:
✔ Java Version 8.1 or Java V8.1
❌ Java version 8.1, Java 8.1, or Java v8.1
When just talking about version, use "version" in lower case.
Example: Use the latest version of Java.
Avoid "may"
Use "can" to indicate ability, or use "might" to indicate possibility.
Example:
Indicating ability:
✔ You can use the command line interface to update your application."
❌ "You may use the command line interface to update your application."
Indicating possibility:
✔ "You might need more advanced features when you are integrating with another application. "
❌ "You may need more advanced features when you are integrating with another application."
Use "issue" when you want to say "run/enter" a command.
Example: At a command prompt, issue the following command:
Abbreviations
Do not use an abbreviation as a noun unless the sentence makes sense when you substitute the
spelled-out form of the term.
Example:
❌ The tutorials are available as PDFs. [portable document formats]
✔ The tutorials are available as PDF files.
Do not use abbreviations as verbs.
Example:
❌ You can FTP the files to the server.
✔ You can use the FTP command to send the files to the server.
Do not use Latin abbreviations.
Use their English equivalents instead. Latin abbreviations are sometimes misunderstood.
Latin English equivalent
e.g. for example
and so on.
etc. When you list a clear sequence of elements such as "1, 2, 3, and so on" and "Monday, Tuesday,
Wednesday, and so on." Otherwise, rewrite the sentence to replace "etc." with something more
descriptive such as "and other output."
i.e. that is
Spell out the full name and its abbreviation when the word appears for the first time. Use
abbreviations in the texts that follow.
Example: Mainframe Virtual Desktop (MVD)
Structure and format
Add "More information" to link to useful resources or related topics at the end of topics where necessary.
Word usage
The following table alphabetically lists the common used words and their usage guidelines.
Do Don't
application app
Capitalize "Server" when it's part of the product
name
Java java
IBM z/OS Management Facility (z/OSMF) zosmf (unless used in syntax)
z/OSMF
ID id
PAX pax
personal computer
PC machine
server
higher
later Do not use to describe versions of software or fix
packs.
macOS MacOS
Node.js node.js
Nodejs
 Do Don't
plug-in plugin
REXX Rexx
UNIX System Services USS
z/OS UNIX System Services
zLUX ZLUX
zLux
Zowe CLI command reference guide
Version: v2.0.x LTS

View detailed documentation on commands, actions, and options in Zowe CLI. You can read an interactive
online version, download a PDF document, or download a ZIP file containing the HTML for the online version.
Currently, this reference documentation only contains the web help for the Zowe CLI core component and
CLI plug-ins maintained by Zowe. As third-party plug-ins are approved under the Zowe V2 LTS
Conformance Program and contribute their web help to Zowe, we will update the documentation
accordingly. To view the web help for V1 conformant plug-ins, click the version drop-menu on the top right
corner of this page and click the link to any previous v1.xx.x version of this page.
Browse online
Download CLI reference in PDF format
Download CLI reference in ZIP format
Zowe API reference
Version: v2.0.x LTS

Find and learn about the Zowe APIs that you can use.
REST API for the Data sets and z/OS Unix Files Services
REST API for the API Gateway service
REST API for the JES Jobs Service
REST API for ZLUX Plug-in
zwe certificate keyring-jcl clean
Version: v2.0.x LTS

zwe > certificate > keyring-jcl > clean

Description
Remove Zowe keyring.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--dataset-prefix,--ds-prefix string yes
--jcllib string yes
--security-dry-run boolean no
--security-product string no
--keyring-owner string yes
--keyring-name string yes
--alias -a string yes
--ca-alias -ca string yes
 Full name Alias Type Required Help message
--ignore-security-failures boolean no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0176E 176 Failed to clean up Zowe keyring "%s".

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
 Exit
Error code code Error message

ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.

ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
 Exit
Error code code Error message

ZWEL0131E 131 Cannot find key %s defined in file %s.

ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate keyring-jcl connect
Version: v2.0.x LTS

zwe > certificate > keyring-jcl > connect

Description
Connect existing certificate to Zowe keyring.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--dataset-prefix,--ds-prefix string yes
--jcllib string yes
--security-dry-run boolean no
--security-product string no
--keyring-owner string yes
--keyring-name string yes
--trust-cas string no
--connect-user string yes
 Full name Alias Type Required Help message
--connect-label string yes
--trust-zosmf boolean no
--zosmf-ca string no
--zosmf-user string no
--ignore-security-failures boolean no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0175E 175 Failed to connect existing certificate to Zowe keyring "%s".
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
 Exit
Error code code Error message

ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate keyring-jcl generate
Version: v2.0.x LTS

zwe > certificate > keyring-jcl > generate

Description
Generate new set of certificate in Zowe keyring.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--dataset-prefix,--ds-prefix string yes
--jcllib string yes
--security-dry-run boolean no
--security-product string no
--keyring-owner string yes
--keyring-name string yes
--domains -d string yes
--alias -a string yes
 Full name Alias Type Required Help message
--ca-alias -ca string yes
--common-name -cn string no
--org-unit string no
--org string no
--locality string no
--state string no
--country string no
--validity string no
--trust-cas string no
--trust-zosmf boolean no
--zosmf-ca string no
--zosmf-user string no
--ignore-security-failures boolean no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
 Full name Alias Type Required Help message
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0174E 174 Failed to generate certificate in Zowe keyring "%s".

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
 Exit
Error code code Error message

ZWEL0106E 106 %s parameter is required.

ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
 Exit
Error code code Error message

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate keyring-jcl import-ds
Version: v2.0.x LTS

zwe > certificate > keyring-jcl > import-ds

Description
Import certificate stored in MVS data set into Zowe keyring.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--dataset-prefix,--ds-prefix string yes
--jcllib string yes
--security-dry-run boolean no
--security-product string no
--keyring-owner string yes
--keyring-name string yes
--alias -a string yes
--trust-cas string no
 Full name Alias Type Required Help message
--trust-zosmf boolean no
--zosmf-ca string no
--zosmf-user string no
--import-ds-name string yes
--import-ds-password string yes
--ignore-security-failures boolean no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0173E 173 Failed to import certificate to Zowe keyring "%s".
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
 Exit
Error code code Error message

ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate keyring-jcl
Version: v2.0.x LTS

zwe > certificate > keyring-jcl

Sub-commands
clean
connect
generate
import-ds

Description
Manage z/OS Keyring with JCL.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
 Full name Alias Type Required Help message
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
 Exit
Error code code Error message

ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
 Exit
Error code code Error message

ZWEL0139E 139 Failed to create directory %s.

ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate pkcs12 create ca
Version: v2.0.x LTS

zwe > certificate > pkcs12 > create > ca

Description
Create a new PKCS12 format certificate authority.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no
--alias -a string yes
--password -p string yes
--common-name -cn string no
--org-unit string no
--org string no
--locality string no
--state string no
 Full name Alias Type Required Help message
--country string no
--validity string no

Inherited from parent command

Full name Alias Type Required Help message
--keystore-dir -d string yes
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0300W %s already exists. This %s will be overwritten during configuration.
ZWEL0158E 158 %s already exists.
ZWEL0168E 168 Failed to create certificate authority %s.
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
 Exit
Error code code Error message

ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate pkcs12 create cert
Version: v2.0.x LTS

zwe > certificate > pkcs12 > create > cert

Description
Create a new PKCS12 format certificate.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no
--keystore -k string yes
--alias -a string yes
--password -p string yes
--common-name -cn string no
--domains -d string no
--ca-alias string yes
--ca-password string yes
 Full name Alias Type Required Help message
--org-unit string no
--org string no
--locality string no
--state string no
--country string no
--validity string no
--key-usage string no
--extended-key-usage string no

Inherited from parent command

Full name Alias Type Required Help message
--keystore-dir -d string yes
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no
Errors
Error code Exit code Error message
ZWEL0300W %s already exists. This %s will be overwritten during configuration.
ZWEL0158E 158 %s already exists.
ZWEL0169E 169 Failed to create certificate "%s".

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
 Exit
Error code code Error message

ZWEL0110E 110 Doesn't have write permission on %s directory.

ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
 Exit
Error code code Error message

ZWEL0140E 140 Failed to translate Zowe configuration (%s).

ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate pkcs12 create
Version: v2.0.x LTS

zwe > certificate > pkcs12 > create

Sub-commands
ca
cert
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--keystore-dir -d string yes

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
 Full name Alias Type Required Help message
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
 Exit
Error code code Error message

ZWEL0110E 110 Doesn't have write permission on %s directory.

ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
 Exit
Error code code Error message

ZWEL0140E 140 Failed to translate Zowe configuration (%s).

ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate pkcs12 export
Version: v2.0.x LTS

zwe > certificate > pkcs12 > export

Description
Export PKCS12 keystore as PEM files.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--keystore -f string yes
--password -p string yes
--private-keys string no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
 Full name Alias Type Required Help message
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0178E 178 Failed to export PKCS12 keystore %s.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
 Exit
Error code code Error message

ZWEL0106E 106 %s parameter is required.

ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
 Exit
Error code code Error message

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate pkcs12 import
Version: v2.0.x LTS

zwe > certificate > pkcs12 > import

Description
Import certificate and/or certificate authorities into PKCS12 keystore.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--keystore -f string yes
--password -p string yes
--alias -a string no
--source-keystore -sf string no
--source-password -sp string no
--source-alias -sa string no
--trust-cas string no

Inherited from parent command

 Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0179E 179 Failed to import certificate (authorities) into keystore %s.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
 Exit
Error code code Error message

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
 Exit
Error code code Error message

ZWEL0135E 135 Failed to find volume of data set %s.

ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate pkcs12 lock
Version: v2.0.x LTS

zwe > certificate > pkcs12 > lock

Description
This command will lock the keystore directory to only be accessible by specified user group.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--keystore-dir -d string yes
--user string yes
--group string yes
--group-permission string no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
 Full name Alias Type Required Help message
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0177E 177 Failed to lock keystore directory %s.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
 Exit
Error code code Error message

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
 Exit
Error code code Error message

ZWEL0135E 135 Failed to find volume of data set %s.

ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate pkcs12 trust-service
Version: v2.0.x LTS

zwe > certificate > pkcs12 > trust-service

Description
This command can detect and trust any service by importing the certificate into truststore.
NOTE: the service must be online and accessible.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--service-name -n string yes
--keystore-dir -d string yes
--keystore -k string yes
--password -p string yes
--host string yes
--port string yes
--alias -a string yes
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0300W %s already exists. This %s will be overwritten during configuration.
ZWEL0170E 170 Failed to trust service "%s".

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
 Exit
Error code code Error message

ZWEL0103E 103 Invalid type of parameter %s.

ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
 Exit
Error code code Error message

ZWEL0133E 133 Data set %s already exists.

ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate pkcs12
Version: v2.0.x LTS

zwe > certificate > pkcs12

Sub-commands
create
export
import
lock
trust-service

Description
Manage PKCS12 format keystore and truststore.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
 Full name Alias Type Required Help message
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
 Exit
Error code code Error message

ZWEL0108E 108 Zowe YAML config file is required.

ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
 Exit
Error code code Error message

ZWEL0138E 138 Failed to update key %s of file %s.

ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate verify-service
Version: v2.0.x LTS

zwe > certificate > verify-service

Description
This command can verify if the service certificate is valid by checking the certificate Common Name (CN)
and Subject Alternate Name (SAN).
NOTE: the service must be online and accessible.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--host string yes
--port string yes

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
 Full name Alias Type Required Help message
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0171E 171 Failed to verify certificate (CN and SAN) of service "%s".

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
 Exit
Error code code Error message

ZWEL0106E 106 %s parameter is required.

ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
 Exit
Error code code Error message

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe certificate
Version: v2.0.x LTS

zwe > certificate

Sub-commands
keyring-jcl
pkcs12
verify-service

Description
Set of commands to help you manage certificates.
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
 Full name Alias Type Required Help message
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
 Exit
Error code code Error message

ZWEL0110E 110 Doesn't have write permission on %s directory.

ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
 Exit
Error code code Error message

ZWEL0140E 140 Failed to translate Zowe configuration (%s).

ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe components install extract
Version: v2.0.x LTS

zwe > components > install > extract

Description
Extract module package and lay down to target directory.
NOTE: this sub-command will be automatically executed by zwe components install , so usually you
don't need to execute this manually.

Examples
Parameters
Full name Alias Type Required Help message
--component-file,--component -o string yes
--auto-encoding -e string no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
 Full name Alias Type Required Help message
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0153E 153 Cannot install Zowe component to system root directory.
ZWEL0154E 154 Temporary directory is empty.
ZWEL0155E 155 Component %s already exists in %s.
ZWEL0167E 167 Cannot find component name from %s package manifest.

Inherited from parent command

Exit
Error code code Error message

ZWEL0156E 156 Component name is not initialized after extract step.

ZWEL0180E 180 Zowe extension directory (zowe.extensionDirectory) is not defined in Zowe

YAML configuration file.

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
 Exit
Error code code Error message

ZWEL0103E 103 Invalid type of parameter %s.

ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
 Exit
Error code code Error message

ZWEL0133E 133 Data set %s already exists.

ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe components install process-hook
Version: v2.0.x LTS

zwe > components > install > process-hook

Description
Process module install hook if exists.
NOTE: this sub-command will be automatically executed by zwe components install , so usually you
don't need to execute this manually.

Examples
Parameters
Full name Alias Type Required Help message
--component-name -n string yes

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
 Full name Alias Type Required Help message
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

ZWEL0156E 156 Component name is not initialized after extract step.

ZWEL0180E 180 Zowe extension directory (zowe.extensionDirectory) is not defined in Zowe

YAML configuration file.

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
 Exit
Error code code Error message

ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
 Exit
Error code code Error message

ZWEL0139E 139 Failed to create directory %s.

ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe components install
Version: v2.0.x LTS

zwe > components > install

Sub-commands
extract
process-hook

Description
Install a Zowe module.
IMPORTANT NOTES, by default, this command will enable the component globally by modifying your YAML
configuration. You can pass --skip-enable to disable this behavior.

Examples
Parameters only for this command
Full name Alias Type Required Help message
--component-file,--component -o string yes
--auto-encoding -e string no
--skip-enable boolean no

Parameters
Inherited from parent command
 Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit Error message
code
ZWEL0156E 156 Component name is not initialized after extract step.
ZWEL0180E 180 Zowe extension directory (zowe.extensionDirectory) is not defined in Zowe
YAML configuration file.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
 Exit
Error code code Error message

ZWEL0102E 102 Invalid parameter %s.

ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
 Exit
Error code code Error message

ZWEL0132E 132 No manifest file found in component %s.

ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe components disable
Version: v2.0.x LTS

zwe > components > disable

Description
Disable a Zowe component.
IMPORTANT NOTES, this command will modify your YAML configuration.

Examples
Parameters
Full name Alias Type Required Help message
--component-name,--component -o string yes
--ha-instance -i string no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
 Full name Alias Type Required Help message
--config -c string no

Errors
Error code Exit code Error message
ZWEL0152E 152 Cannot find component %s.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
 Exit
Error code code Error message

ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
 Exit
Error code code Error message

ZWEL0139E 139 Failed to create directory %s.

ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe components enable
Version: v2.0.x LTS

zwe > components > enable

Description
Enable a Zowe component.
IMPORTANT NOTES, this command will modify your YAML configuration.

Examples
Parameters
Full name Alias Type Required Help message
--component-name,--component -o string yes
--ha-instance -i string no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
 Full name Alias Type Required Help message
--config -c string no

Errors
Error code Exit code Error message
ZWEL0152E 152 Cannot find component %s.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
 Exit
Error code code Error message

ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
 Exit
Error code code Error message

ZWEL0139E 139 Failed to create directory %s.

ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe components
Version: v2.0.x LTS

zwe > components

Sub-commands
disable
enable
install

Examples
Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
 Exit
Error code code Error message

ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe init apfauth
Version: v2.0.x LTS

zwe > init > apfauth

Description
This command will APF authorize load library for you.
NOTE: You require proper permission to run APF authorize command.
These Zowe YAML configurations showing with sample values are used:
zowe.setup.dataset.prefix shows where the SZWEAUTH data set is installed.

zowe.setup.dataset.authLoadlib is the user custom APF LOADLIB. This field is optional. If it's
not defined, SZWEAUTH from zowe.setup.dataset.prefix data set will be APF authorized.
zowe.setup.dataset.authPluginLib is the user custom APF PLUGINLIB. You can install Zowe
ZIS plugins into this load library.

Examples
Parameters
Full name Alias Type Required Help message
--security-dry-run boolean no
--ignore-security-failures boolean no

Inherited from parent command

Full name Alias Type Required Help message
 Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no
--skip-security-setup boolean no
--security-dry-run boolean no
--ignore-security-failures boolean no
--update-config boolean no
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0157E 157 %s (%s) is not defined in Zowe YAML configuration file.

Inherited from parent command

Exit
Error code code Error message
 Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
 Exit
Error code code Error message

ZWEL0123E 123 This function is only available in Zowe Containerization deployment.

ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe init certificate
Version: v2.0.x LTS

zwe > init > certificate

Description
This command will generate certificate used by Zowe services.
If you specify --update-config with this command, these configurations could be written back to your
Zowe YAML configuration file:
zowe.certificate based on your zowe.setup.certificate configuration.

These Zowe YAML configurations showing with sample values are used:
zowe.setup.certificate.type is the type of certificate. Valid values are "PKCS12" (USS
keystore) or "JCERACFKS" (z/OS keyring).
zowe.setup.certificate.dname is the distinguished name of the certificate. You can define
caCommonName , commonName , orgUnit , org , locality , state , and / or country .
These configurations are optional.
zowe.setup.certificate.validity is the validity days of the certificate. This is optional.

zowe.setup.certificate.san is the Subject Alternative Name (s) of the certificate if they

are different from zowe.externalDomains . Please note, for `JCERACFKS`` type, with limitation of
RACDCERT command, this should contain exact one hostname (domain) and one IP address.
zowe.setup.certificate.importCertificateAuthorities is the list of certificate authorities
will be imported to Zowe PKCS12 keystore or JCERACFKS keyring. Please note, for JCERACFKS type,
only maximum 2 CAs is supported. If you are using PKCS12 certificate, this should be USS files in PEM
format. If you are using JCERACFKS certificate, this should be certificate labels on the z/OS system.
zOSMF.host and zOSMF.port is the z/OSMF service information. This is required if you are using
z/OSMF as authentication service.
zowe.verifyCertificates indicates how Zowe should validate the certificate of services
registered under Zowe APIML. Valid values are "STRICT", "NONSTRICT" or "DISABLED". If this is
"STRICT", this command will try to validate the z/OSMF service certificate if z/OSMF is defined.
For PKCS12 certificate users,
 zowe.setup.certificate.pkcs12.directory is the directory where you plan to store the
PKCS12 keystore and truststore. This is required if zowe.setup.certificate.type is PKCS12 .
zowe.setup.certificate.pkcs12.lock is a boolean configuration to tell if we should lock the
PKCS12 keystore directory only for Zowe runtime user and group. Default value is true.
zowe.setup.security.groups.admin and zowe.setup.security.users.zowe will be the
default owner of keystore directory.
You can also define name , password , caAlias and caPassword under
zowe.setup.certificate.pkcs12 to customized keystore and truststore. These configurations
are optional, but it is recommended to update them from default values.
Define zowe.setup.certificate.pkcs12.import.keystore if you already acquired certificate
from other CA, stored them in PKCS12 format, and want to import into Zowe PKCS12 keystore.
zowe.setup.certificate.pkcs12.import.password is the password for keystore defined in
zowe.setup.certificate.pkcs12.import.keystore .

zowe.setup.certificate.pkcs12.import.alias is the original certificate alias defined in

zowe.setup.certificate.pkcs12.import.keystore . After imported, the certificate will be
saved as alias specified in zowe.setup.certificate.pkcs12.name .
For JCERACFKS certificate (z/OS keyring) users,
zowe.setup.certificate.keyring.owner is the keyring owner. It's optional and default value is
zowe.setup.security.users.zowe . If it's also not defined, the default value is ZWESVUSR .

zowe.setup.certificate.keyring.name is the keyring name will be created on z/OS. This is

required if zowe.setup.certificate.type is JCERACFKS .
If you want to let Zowe to generate new certificate,
You can also customize label and caLabel under zowe.setup.certificate.keyring if
you want to generate new certificate. Default value of label is localhost and default value of
caLabel is localca .

If you want to import certificate stored in MVS data set into Zowe keyring,
zowe.setup.certificate.keyring.connect.dsName is required in this case. It tells Zowe
the data set where the certificate stored.
zowe.setup.certificate.keyring.connect.password is the password when importing
the certificate.
The certificate will be imported with label defined in
zowe.setup.certificate.keyring.label .

If you want to connect existing certificate into Zowe keyring,

 zowe.setup.certificate.keyring.connect.user is required and tells Zowe the owner of
existing certificate. This field can have value of SITE .
zowe.setup.certificate.keyring.connect.label is also required and tells Zowe the
label of existing certificate.
If zowe.verifyCertificates is not DISABLED , and z/OSMF host ( zOSMF.host ) is provided,
Zowe will try to trust z/OSMF certificate.
If you are using RACF security manager, Zowe will try to automatically detect the z/OSMF CA
based on certificate owner specified by zowe.setup.certificate.keyring.zOSMF.user .
Default value of this field is IZUSVR . If the automatic detection failed, you will need to define
zowe.setup.certificate.keyring.zOSMF.ca indicates what is the label of z/OSMF root
certificate authority.
If you are using ACF2 or TSS (Top Secret) security manager,
zowe.setup.certificate.keyring.zOSMF.ca is required to indicates what is the label of
z/OSMF root certificate authority.

Examples
Parameters
Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no
--update-config boolean no
--ignore-security-failures boolean no

Inherited from parent command

Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no
--skip-security-setup boolean no
 Full name Alias Type Required Help message
--security-dry-run boolean no
--ignore-security-failures boolean no
--update-config boolean no
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit Error message
code
ZWEL0157E 157 %s (%s) is not defined in Zowe YAML configuration file.
ZWEL0164E 164 Value of %s (%s) defined in Zowe YAML configuration file is invalid. Valid
values are %s.

Inherited from parent command

Exit
Error code code Error message
 Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
 Exit
Error code code Error message

ZWEL0123E 123 This function is only available in Zowe Containerization deployment.

ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe init mvs
Version: v2.0.x LTS

zwe > init > mvs

Description
This command will prepare Zowe custom data sets.
These Zowe YAML configurations showing with sample values are used:
zowe.setup.dataset.prefix shows where the SZWESAMP and SZWEAUTH data sets are installed.

Below data sets will be initialized by this command:

zowe.setup.dataset.parmlib is the user custom parameter library. Zowe server command may
generate sample PARMLIB members and stores here.
zowe.setup.dataset.jcllib is the custom JCL library. Zowe server command may generate
sample JCLs and put into this data set.
zowe.setup.dataset.authLoadlib is the user custom APF LOADLIB. This field is optional. If this
is defined, members of SZWEAUTH will be copied over to this data set. This loadlib requires APF
authorize.
zowe.setup.dataset.authPluginLib is the user custom APF PLUGINLIB. You can install Zowe
ZIS plugins into this load library. This loadlib requires APF authorize.
NOTE: Existing members in custom data sets will not be overwritten by default. You can pass --allow-
overwrite parameters to force update.

Examples
Parameters
Full name Alias Type Required Help message
 Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no

Inherited from parent command

Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no
--skip-security-setup boolean no
--security-dry-run boolean no
--ignore-security-failures boolean no
--update-config boolean no
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit Error message
code
 Error code Exit Error message
code
ZWEL0157E 157 %s (%s) is not defined in Zowe YAML configuration file.

ZWEL0300W %s already exists. This data set member will be overwritten during
configuration.

ZWEL0301W %s already exists and will not be overwritten. For upgrades, you must use --
allow-overwrite.
ZWEL0158E 158 %s already exists.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
 Exit
Error code code Error message

ZWEL0108E 108 Zowe YAML config file is required.

ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
 Exit
Error code code Error message

ZWEL0138E 138 Failed to update key %s of file %s.

ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe init security
Version: v2.0.x LTS

zwe > init > security

Description
This command will run ZWESECUR jcl.
NOTE: You require proper permission to run security configuration.
These Zowe YAML configurations showing with sample values are used:
zowe.setup.dataset.prefix shows where the SZWESAMP data set is installed,

zowe.setup.dataset.jcllib is the custom JCL library. Zowe will create customized ZWESECUR
JCL here before applying it.
zowe.setup.security.product is security product. Can be RACF , ACF2 , or TSS . This
configuration is optional. Default value is RACF .
zowe.setup.security.groups.admin is the group for Zowe administrators. This configuration is
optional. Default value is ZWEADMIN .
zowe.setup.security.groups.stc is the group for Zowe started tasks. This configuration is
optional. Default value is ZWEADMIN .
zowe.setup.security.groups.sysProg is system programmer user ID/group. This configuration
is optional. Default value is ZWEADMIN .
zowe.setup.security.users.zowe is the userid for Zowe started task. This configuration is
optional. Default value is ZWESVUSR .
zowe.setup.security.users.zis is userid for ZIS started task. This configuration is optional.
Default value is ZWESIUSR .
zowe.setup.security.stcs.zowe is Zowe started task name. This configuration is optional.
Default value is ZWESLSTC .
zowe.setup.security.stcs.zis is ZIS started task name. This configuration is optional. Default
value is ZWESISTC .
zowe.setup.security.stcs.aux is ZIS auxiliary started task name. This configuration is optional.
Default value is ZWESASTC .
Examples
Parameters
Full name Alias Type Required Help message
--security-dry-run boolean no
--ignore-security-failures boolean no

Inherited from parent command

Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no
--skip-security-setup boolean no
--security-dry-run boolean no
--ignore-security-failures boolean no
--update-config boolean no
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no
Errors
Error code Exit code Error message
ZWEL0157E 157 %s (%s) is not defined in Zowe YAML configuration file.
ZWEL0159E 159 Failed to modify %s.
ZWEL0160E 160 Failed to write to %s. Please check if target data set is opened by others.
ZWEL0161E 161 Failed to run JCL %s.
ZWEL0161W Failed to run JCL %s.
ZWEL0162E 162 Failed to find job %s result.
ZWEL0162W Failed to find job %s result.
ZWEL0163E 163 Job %s ends with code %s.
ZWEL0163W Job %s ends with code %s.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
 Exit
Error code code Error message

ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
 Exit
Error code code Error message

ZWEL0134E 134 Failed to find SMS status of data set %s.

ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe init stc
Version: v2.0.x LTS

zwe > init > stc

Description
This command will copy Zowe started tasks ZWESLSTC , ZWESISTC , ZWESASTC to your target
procedure library.
NOTE: You require proper permission to write to target procedure library.
These Zowe YAML configurations showing with sample values are used:
zowe.setup.dataset.prefix shows where the SZWESAMP data set is installed,

zowe.setup.dataset.proclib shows what is the target procedure library.

zowe.setup.dataset.parmlib is the user custom parameter library. Zowe server command may
generate sample PARMLIB members and stores here.
zowe.setup.dataset.jcllib is the custom JCL library. Zowe will create temporary started tasks
here before putting into target procedure library.
zowe.setup.dataset.authLoadlib is the user custom APF LOADLIB. This field is optional. If this
is not defined, SZWEAUTH from zowe.setup.dataset.prefix data set will be used as STEPLIB in
STCs.
zowe.setup.security.stcs.zowe is Zowe started task name. This configuration is optional.
Default value is ZWESLSTC .
zowe.setup.security.stcs.zis is ZIS started task name. This configuration is optional. Default
value is ZWESISTC .
zowe.setup.security.stcs.aux is ZIS auxiliary started task name. This configuration is optional.
Default value is ZWESASTC .

Examples
Parameters
 Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no

Inherited from parent command

Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no
--skip-security-setup boolean no
--security-dry-run boolean no
--ignore-security-failures boolean no
--update-config boolean no
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit Error message
code
 Error code Exit Error message
code
ZWEL0157E 157 %s (%s) is not defined in Zowe YAML configuration file.
ZWEL0300W %s already exists. This data set member will be overwritten during
configuration.

ZWEL0301W %s already exists and will not be overwritten. For upgrades, you must use --
allow-overwrite.
ZWEL0143E 143 Cannot find data set member %s. You may need to re-run zwe install .
ZWEL0158E 158 %s already exists.
ZWEL0159E 159 Failed to modify %s.
ZWEL0160E 160 Failed to write to %s. Please check if target data set is opened by others.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
 Exit
Error code code Error message

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
 Exit
Error code code Error message

ZWEL0135E 135 Failed to find volume of data set %s.

ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe init vsam
Version: v2.0.x LTS

zwe > init > vsam

Description
This command will run ZWECSVSM jcl to create VSAM data set for Zowe APIML Caching Service.
These Zowe YAML configurations showing with sample values are used:
zowe.setup.dataset.prefix shows where the SZWESAMP data set is installed,

zowe.setup.dataset.jcllib is the custom JCL library. Zowe will create customized ZWESECUR
JCL here before applying it.
zowe.setup.vsam.mode indicates whether the VSAM will utilize Record Level Sharing (RLS)
services or not. Valid value is RLS or NONRLS .
zowe.setup.vsam.volume indicates the name of volume. This field is required if VSAM mode is
NONRLS .

zowe.setup.vsam.storageClass indicates the name of RLS storage class. This field is required if
VSAM mode is RLS .
components.caching-service.storage.mode indicates what storage Zowe Caching Service will
use. Only if this value is VSAM , this command will try to create VSAM data set.
components.caching-service.storage.vsam.name defines the VSAM data set name.

Examples
Parameters
Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no

Inherited from parent command

 Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no
--skip-security-setup boolean no
--security-dry-run boolean no
--ignore-security-failures boolean no
--update-config boolean no
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit Error message
code
ZWEL0157E 157 %s (%s) is not defined in Zowe YAML configuration file.

ZWEL0300W %s already exists. This data set member will be overwritten during
configuration.

ZWEL0301W %s already exists and will not be overwritten. For upgrades, you must use --
allow-overwrite.
 Error code Exit Error message
code
ZWEL0158E 158 %s already exists.
ZWEL0159E 159 Failed to modify %s.
ZWEL0160E 160 Failed to write to %s. Please check if target data set is opened by others.
ZWEL0161E 161 Failed to run JCL %s.
ZWEL0162E 162 Failed to find job %s result.
ZWEL0163E 163 Job %s ends with code %s.
ZWEL0301W 0 Zowe Caching Service is not configured to use VSAM. Command skipped.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
 Exit
Error code code Error message

ZWEL0106E 106 %s parameter is required.

ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
 Exit
Error code code Error message

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe init
Version: v2.0.x LTS

zwe > init

Sub-commands
apfauth
certificate
mvs
security
stc
vsam

Description
Init Zowe instance based on zowe.yaml configuration.
You can find an example zowe.yaml in Zowe runtime directory folder.
This command will run these sub-commands in sequence:
zwe init mvs

zwe init vsam

zwe init apfauth

zwe init security

zwe init certificate

zwe init stc

If you pass --skip-security-setup with this command, zwe init apfauth and zwe init
security steps will be skipped.

If you pass --update-config with this command, these configurations could be written back to your
Zowe YAML configuration file:
 zowe.runtimeDirectory based on where your zwe command is located, and if it is not defined,
zowe.certificate based on your zowe.setup.certificate configuration,

java.home based on your current JAVA_HOME or automatic detection,

node.home based on your current NODE_HOME or automatic detection.

IMPORTANT, if you modify any of the values below, it's suggested to re-run relevant zwe init command
to make them taking effect.
These Zowe YAML configurations showing with sample values are used:
zowe.setup.dataset.prefix shows where the SZWEAUTH data set is installed.

zowe.setup.dataset.parmlib is the user custom parameter library. Zowe server command may
generate sample PARMLIB members and stores here.
zowe.setup.dataset.jcllib is the custom JCL library. Zowe server command may generate
sample JCLs and put into this data set.
zowe.setup.dataset.authLoadlib is the user custom APF LOADLIB. This field is optional. If this
is defined, members of SZWEAUTH will be copied over to this data set and it will be APF authorized. If
it's not defined, SZWEAUTH from zowe.setup.dataset.prefix data set will be APF authorized.
zowe.setup.dataset.authPluginLib is the user custom APF PLUGINLIB. You can install Zowe
ZIS plugins into this load library. This loadlib requires APF authorize.
zowe.setup.security.product is security product. Can be RACF , ACF2 , or TSS . This
configuration is optional. Default value is RACF .
zowe.setup.security.groups.admin is the group for Zowe administrators. This configuration is
optional. Default value is ZWEADMIN .
zowe.setup.security.groups.stc is the group for Zowe started tasks. This configuration is
optional. Default value is ZWEADMIN .
zowe.setup.security.groups.sysProg is system programmer user ID/group. This configuration
is optional. Default value is ZWEADMIN .
zowe.setup.security.users.zowe is the userid for Zowe started task. This configuration is
optional. Default value is ZWESVUSR .
 zowe.setup.security.users.zis is userid for ZIS started task. This configuration is optional.
Default value is ZWESIUSR .
zowe.setup.security.stcs.zowe is Zowe started task name. This configuration is optional.
Default value is ZWESLSTC .
zowe.setup.security.stcs.zis is ZIS started task name. This configuration is optional. Default
value is ZWESISTC .
zowe.setup.security.stcs.aux is ZIS auxiliary started task name. This configuration is optional.
Default value is ZWESASTC .
zowe.setup.certificate.type is the type of certificate. Valid values are "PKCS12" (USS
keystore) or "JCERACFKS" (z/OS keyring).
zowe.setup.certificate.dname is the distinguished name of the certificate. You can define
caCommonName , commonName , orgUnit , org , locality , state , and / or country .
These configurations are optional.
zowe.setup.certificate.validity is the validity days of the certificate. This is optional.

zowe.setup.certificate.san is the Subject Alternative Name (s) of the certificate if they

are different from zowe.externalDomains . Please note, for JCERACFKS type, with limitation of
RACDCERT command, this should contain exact one hostname (domain) and one IP address.
zowe.setup.certificate.importCertificateAuthorities is the list of certificate authorities
will be imported to Zowe PKCS12 keystore or JCERACFKS keyring. Please note, for JCERACFKS type,
only maximum 2 CAs is supported. If you are using PKCS12 certificate, this should be USS files in PEM
format. If you are using JCERACFKS certificate, this should be certificate labels on the z/OS system.
For PKCS12 certificate users,
zowe.setup.certificate.pkcs12.directory is the directory where you plan to store the
PKCS12 keystore and truststore. This is required if zowe.setup.certificate.type is PKCS12 .
zowe.setup.certificate.pkcs12.lock is a boolean configuration to tell if we should lock the
PKCS12 keystore directory only for Zowe runtime user and group. Default value is true.
You can also define name , password , caAlias and caPassword under
zowe.setup.certificate.pkcs12 to customized keystore and truststore. These configurations
are optional, but it is recommended to update them from default values.
 Define zowe.setup.certificate.pkcs12.import.keystore if you already acquired certificate
from other CA, stored them in PKCS12 format, and want to import into Zowe PKCS12 keystore.
zowe.setup.certificate.pkcs12.import.password is the password for keystore defined in
zowe.setup.certificate.pkcs12.import.keystore .

zowe.setup.certificate.pkcs12.import.alias is the original certificate alias defined in

zowe.setup.certificate.pkcs12.import.keystore . After imported, the certificate will be
saved as alias specified in zowe.setup.certificate.pkcs12.name .
For JCERACFKS certificate (z/OS keyring) users,
zowe.setup.certificate.keyring.owner is the keyring owner. It's optional and default value is
zowe.setup.security.users.zowe . If it's also not defined, the default value is ZWESVUSR .

zowe.setup.certificate.keyring.name is the keyring name will be created on z/OS. This is

required if zowe.setup.certificate.type is JCERACFKS .
If you want to let Zowe to generate new certificate,
You can also customize label and caLabel under zowe.setup.certificate.keyring if
you want to generate new certificate. Default value of label is localhost and default value of
caLabel is localca .

If you want to import certificate stored in MVS data set into Zowe keyring,
zowe.setup.certificate.keyring.connect.dsName is required in this case. It tells Zowe
the data set where the certificate stored.
zowe.setup.certificate.keyring.connect.password is the password when importing
the certificate.
The certificate will be imported with label defined in
zowe.setup.certificate.keyring.label .

If you want to connect existing certificate into Zowe keyring,

zowe.setup.certificate.keyring.connect.user is required and tells Zowe the owner of
existing certificate. This field can have value of SITE .
zowe.setup.certificate.keyring.connect.label is also required and tells Zowe the
label of existing certificate.
 If zowe.verifyCertificates is not DISABLED , and z/OSMF host ( zOSMF.host ) is provided,
Zowe will try to trust z/OSMF certificate.
If you are using RACF security manager, Zowe will try to automatically detect the z/OSMF CA
based on certificate owner specified by zowe.setup.certificate.keyring.zOSMF.user .
Default value of this field is IZUSVR . If the automatic detection failed, you will need to define
zowe.setup.certificate.keyring.zOSMF.ca indicates what is the label of z/OSMF root
certificate authority.
If you are using ACF2 or TSS (Top Secret) security manager,
zowe.setup.certificate.keyring.zOSMF.ca is required to indicates what is the label of
z/OSMF root certificate authority.
zowe.setup.vsam.mode indicates whether the VSAM will utilize Record Level Sharing (RLS)
services or not. Valid value is RLS or NONRLS .
zowe.setup.vsam.volume indicates the name of volume. This field is required if VSAM mode is
NONRLS .

zowe.setup.vsam.storageClass indicates the name of RLS storage class. This field is required if
VSAM mode is RLS .
zowe.verifyCertificates indicates how Zowe should validate the certificate of services
registered under Zowe APIML. Valid values are "STRICT", "NONSTRICT" or "DISABLED". If this is
"STRICT", this command will try to validate the z/OSMF service certificate if z/OSMF is defined.
zOSMF.host and zOSMF.port is the z/OSMF service information. This is required if you are using
z/OSMF as authentication service.
components.caching-service.storage.mode indicates what storage Zowe Caching Service will
use. Only if this value is VSAM , this command will try to create VSAM data set.
components.caching-service.storage.vsam.name defines the VSAM data set name.

Examples
Parameters
 Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no
--skip-security-setup boolean no
--security-dry-run boolean no
--ignore-security-failures boolean no
--update-config boolean no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message
 Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
 Exit
Error code code Error message

ZWEL0123E 123 This function is only available in Zowe Containerization deployment.

ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe internal config get
Version: v2.0.x LTS

zwe > internal > config > get

Description
Return value of a configuration defined in YAML configuration.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--ha-instance -i string no
--path -p string yes

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
 Full name Alias Type Required Help message
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
 Exit
Error code code Error message

ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
 Exit
Error code code Error message

ZWEL0139E 139 Failed to create directory %s.

ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe internal config set
Version: v2.0.x LTS

zwe > internal > config > set

Description
Set value of a configuration and write back to the YAML configuration.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--ha-instance -i string no
--path -p string yes
--value -e string no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
 Full name Alias Type Required Help message
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
 Exit
Error code code Error message

ZWEL0108E 108 Zowe YAML config file is required.

ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
 Exit
Error code code Error message

ZWEL0138E 138 Failed to update key %s of file %s.

ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe internal config
Version: v2.0.x LTS

zwe > internal > config

Sub-commands
get
set
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no
Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
 Exit
Error code code Error message

ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe internal container cleanup
Version: v2.0.x LTS

zwe > internal > container > cleanup

Description
Clean up Kubernetes runtime.
Currently this command will remove all outdated static definitions.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
 Exit
Error code code Error message

ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe internal container init
Version: v2.0.x LTS

zwe > internal > container > init

Description
Initialize special runtime environment required by Zowe containerization.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
 Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
 Exit
Error code code Error message

ZWEL0123E 123 This function is only available in Zowe Containerization deployment.

ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe internal container prestop
Version: v2.0.x LTS

zwe > internal > container > prestop

Description
Actions will be executed before a service is stopped.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Parameters
Full name Alias Type Required Help message
--ha-instance -i string no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no
Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
 Exit
Error code code Error message

ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe internal container
Version: v2.0.x LTS

zwe > internal > container

Sub-commands
cleanup
init
prestop

Description
Internal commands to help manager workloads in Zowe containers.
NOTE: these internal commands are only used by Zowe Containerization use scenario.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
 Full name Alias Type Required Help message
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
 Exit
Error code code Error message

ZWEL0110E 110 Doesn't have write permission on %s directory.

ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
 Exit
Error code code Error message

ZWEL0140E 140 Failed to translate Zowe configuration (%s).

ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe internal start component
Version: v2.0.x LTS

zwe > internal > start > component

Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--component -o string yes
--run-in-background boolean no

Inherited from parent command

Full name Alias Type Required Help message
--ha-instance -i string no
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
 Full name Alias Type Required Help message
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
 Exit
Error code code Error message

ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
 Exit
Error code code Error message

ZWEL0142E 142 Failed to refresh APIML static registrations.

ZWEL0172E Component %s has %s defined but the file is missing.
zwe internal start prepare
Version: v2.0.x LTS

zwe > internal > start > prepare

Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Inherited from parent command
Full name Alias Type Required Help message
--ha-instance -i string no
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
 Error code Exit Error message
code
ZWEL0141E 141 User %s does not have write permission on %s.
ZWEL0302W You are running the Zowe process under user id IZUSVR. This is not
recommended and may impact your z/OS MF server negatively.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
 Exit
Error code code Error message

ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
 Exit
Error code code Error message

ZWEL0142E 142 Failed to refresh APIML static registrations.

ZWEL0172E Component %s has %s defined but the file is missing.
zwe internal start
Version: v2.0.x LTS

zwe > internal > start

Sub-commands
component
prepare
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--ha-instance -i string no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
 Full name Alias Type Required Help message
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
 Exit
Error code code Error message

ZWEL0110E 110 Doesn't have write permission on %s directory.

ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
 Exit
Error code code Error message

ZWEL0140E 140 Failed to translate Zowe configuration (%s).

ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe internal get-launch-components
Version: v2.0.x LTS

zwe > internal > get-launch-components

Description
Return component list should be started in specified HA instance.
NOTE: This command only returns a list of enabled components with start command.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--ha-instance -i string no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
 Full name Alias Type Required Help message
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
 Exit
Error code code Error message

ZWEL0110E 110 Doesn't have write permission on %s directory.

ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
 Exit
Error code code Error message

ZWEL0140E 140 Failed to translate Zowe configuration (%s).

ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe internal
Version: v2.0.x LTS

zwe > internal

Sub-commands
config
container
get-launch-components
start

Description
Commands will be executed internally by other Zowe commands.
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
 Full name Alias Type Required Help message
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
 Exit
Error code code Error message

ZWEL0110E 110 Doesn't have write permission on %s directory.

ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
 Exit
Error code code Error message

ZWEL0140E 140 Failed to translate Zowe configuration (%s).

ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe migrate for kubernetes
Version: v2.0.x LTS

zwe > migrate > for > kubernetes

Description
Migrate your YAML configuration on z/OS for Kubernetes.
This script will create zowe-config ConfigMap and zowe-certificates-secret Secret for
Kubernetes deployment.
To manually create zowe-config ConfigMap , the data section should contain a key zowe.yaml
with string value of your zowe.yaml used on z/OS.
To manually create zowe-certificates-secret Secret , you need 2 entries under data section:
keystore.p12 : which is base64 encoded PKCS#12 keystore,

truststore.p12 : which is base64 encoded PKCS#12 truststore.

And 3 entries under stringData section:

keystore.key : is the PEM format of certificate private key,

keystore.cer : is the PEM format of the certificate,

ca.cer : is the PEM format of the certificate authority.

In order to make certificates working in Kubernetes, the certificate you are using should have these domains
defined in certificate Subject Alt Name (SAN):
your external domains to access Zowe APIML Gateway Service running in Kubernetes cluster,
*.<k8s-namespace>.svc.<k8s-cluster-name>

*.discovery-service.<k8s-namespace>.svc.<k8s-cluster-name>

*.gateway-service.<k8s-namespace>.svc.<k8s-cluster-name>

*.<k8s-namespace>.pod.<k8s-cluster-name>
<k8s-namespace> is the Kubernetes Namespace you installed Zowe into. And <k8s-cluster-name>
is the Kubernetes cluster name, which usually should be cluster.local .
Without the additional domains in SAN, you may see warnings/errors related to certificate validation.
If you cannot add those domains into certificate Subject Alt Name (SAN), you can change
zowe.verifyCertificates to NONSTRICT mode. Zowe components will not validate domain names
but will continue to validate certificate chain, validity and whether it's trusted in Zowe truststore.
IMPORTANT: It's not recommended to disable zowe.verifyCertificates .
NOTES: With below conditions, this migration script will re-generate a new set of certificate for you with
proper domain names listed above.
you use zwe init command to initialize Zowe,
use PKCS#12 format keystore by defining zowe.setup.certificate.type: PKCS12
did not define zowe.setup.certificate.pkcs12.import.keystore and let zwe command to
generate PKCS12 keystore for you
enabled STRICT mode zowe.verifyCertificates .

Parameters
Full name Alias Type Required Help message
--domains -d string no
--external-port string no
--k8s-namespace string no
--k8s-cluster-name string no
--alias -a string no
--password -p string no
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
 Exit
Error code code Error message

ZWEL0106E 106 %s parameter is required.

ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
 Exit
Error code code Error message

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe migrate for
Version: v2.0.x LTS

zwe > migrate > for

Sub-commands
kubernetes

Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message
 Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
 Exit
Error code code Error message

ZWEL0123E 123 This function is only available in Zowe Containerization deployment.

ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe migrate
Version: v2.0.x LTS

zwe > migrate

Sub-commands
for

Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message
 Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
 Exit
Error code code Error message

ZWEL0123E 123 This function is only available in Zowe Containerization deployment.

ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe sample sub deep
Version: v2.0.x LTS

zwe > sample > sub > deep

Description
Sample of deep embedded sub-command.
Also inherit parameters from upper level.
NOTE: This command is to demonstrate how zwe command works. There are no real meaningful
functionalities defined in this command and sub-commands.
WARNING: This command is for experimental purposes and could be changed in the future releases.###
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--another-parameter -p boolean no

Inherited from parent command

Full name Alias Type Required Help message
--target-dir,--target -d string yes
--auto-encoding -e string no
 Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
 Exit
Error code code Error message

ZWEL0106E 106 %s parameter is required.

ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
 Exit
Error code code Error message

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe sample sub second
Version: v2.0.x LTS

zwe > sample > sub > second

Description
Sample of second sub-command.
NOTE: This command is to demonstrate how zwe command works. There are no real meaningful
functionalities defined in this command and sub-commands.
WARNING: This command is for experimental purposes and could be changed in the future releases.###
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Inherited from parent command
Full name Alias Type Required Help message
--target-dir,--target -d string yes
--auto-encoding -e string no
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
 Full name Alias Type Required Help message
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
 Exit
Error code code Error message

ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
 Exit
Error code code Error message

ZWEL0139E 139 Failed to create directory %s.

ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe sample sub
Version: v2.0.x LTS

zwe > sample > sub

Sub-commands
deep
second

Description
A sample sub-command.
NOTE: This command is to demonstrate how zwe command works. There are no real meaningful
functionalities defined in this command and sub-commands.
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Full name Alias Type Required Help message
--target-dir,--target -d string yes
--auto-encoding -e string no

Inherited from parent command

 Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
 Exit
Error code code Error message

ZWEL0106E 106 %s parameter is required.

ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
 Exit
Error code code Error message

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe sample test
Version: v2.0.x LTS

zwe > sample > test

Description
A sample command.
NOTE: This command is to demonstrate how zwe command works. There are no real meaningful
functionalities defined in this command and sub-commands.
WARNING: This command is for experimental purposes and could be changed in the future releases.###
Inherited from parent command
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
 Full name Alias Type Required Help message
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
 Exit
Error code code Error message

ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
 Exit
Error code code Error message

ZWEL0142E 142 Failed to refresh APIML static registrations.

ZWEL0172E Component %s has %s defined but the file is missing.
zwe sample
Version: v2.0.x LTS

zwe > sample

Sub-commands
sub
test

Description
This is a sample command.
NOTE: This command is to demonstrate how zwe command works. There are no real meaningful
functionalities defined in this command and sub-commands.
WARNING: This command is for experimental purposes and could be changed in the future releases.

Examples
Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
 Full name Alias Type Required Help message
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
 Exit
Error code code Error message

ZWEL0110E 110 Doesn't have write permission on %s directory.

ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
 Exit
Error code code Error message

ZWEL0140E 140 Failed to translate Zowe configuration (%s).

ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe support verify-fingerprints
Version: v2.0.x LTS

zwe > support > verify-fingerprints

Parameters
Inherited from parent command
Full name Alias Type Required Help message
--target-dir string no
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit Error message
code
ZWEL0113E 113 Failed to find Zowe version. Please validate your Zowe directory.
ZWEL0150E 150 Failed to find file %s. Zowe runtimeDirectory is invalid.
 Error code Exit Error message
code

ZWEL0151E 151 Failed to create temporary file %s. Please check permission or volume free
space.
ZWEL0181E 181 Failed to verify Zowe file fingerprints.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
 Exit
Error code code Error message

ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
 Exit
Error code code Error message

ZWEL0142E 142 Failed to refresh APIML static registrations.

ZWEL0172E Component %s has %s defined but the file is missing.
zwe support
Version: v2.0.x LTS

zwe > support

Sub-commands
verify-fingerprints

Description
Collect and package Zowe runtime information for support purpose.
This command will collect these information:
Environment
z/OS version
Java version
Node.js version
Zowe configurations
Zowe manifest.json
Zowe configuration file
Zowe installation logs
Zowe PKCS#12 keystore if used
Zowe temporary configuration files under <workspace>/.env
Zowe APIML static registration files under <workspace>/api-mediation/api-defs
Zowe runtime
Active running Zowe processes
Zowe job log
Zowe fingerprints and validation result

Parameters
 Full name Alias Type Required Help message
--target-dir string no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Inherited from parent command
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
 Exit
Error code code Error message

ZWEL0103E 103 Invalid type of parameter %s.

ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
 Exit
Error code code Error message

ZWEL0133E 133 Data set %s already exists.

ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe install
Version: v2.0.x LTS

zwe > install

Description
After you extract Zowe convenience build, you can run this command to install MVS data sets.
If you are using SMPE build, you can skip this command since MVS data sets are already prepared during
SMPE install.
These Zowe YAML configurations showing with sample values are used:
Expected outputs:
Will create these data sets under zowe.setup.dataset.prefix definition:
SZWEAUTH contains few Zowe load modules (++PROGRAM).

SZWESAMP contains several sample configurations.

SZWEEXEC contains few utilities used by Zowe.

Examples
Parameters
Full name Alias Type Required Help message
--allow-overwrite,--allow-overwritten boolean no
--dataset-prefix,--ds-prefix string no

Inherited from parent command

 Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit Error message
code
ZWEL0157E 157 %s (%s) is not defined in Zowe YAML configuration file.
ZWEL0300W %s already exists. Members in this data set will be overwritten.
ZWEL0301W %s already exists and will not be overwritten. For upgrades, you must use --
allow-overwrite.
ZWEL0158E 158 %s already exists.

Inherited from parent command

Exit
Error code code Error message
 Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
 Exit
Error code code Error message

ZWEL0123E 123 This function is only available in Zowe Containerization deployment.

ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe start
Version: v2.0.x LTS

zwe > start

Description
Start Zowe with main started task.
These Zowe YAML configurations showing with sample values are used:
zowe.setup.security.stcs.zowe is Zowe started task name. This configuration is optional.
Default value is ZWESLSTC .
zowe.jobname is the optional customized job name to start Zowe. If it's empty, the start command
will not pass JOBNAME= option to S command.
haInstances.<ha-instance>.sysname is the SYSNAME of the target HA instance. If you pass -
-ha-instance parameter, this is the SYSNAME the start command will be routed to.

Examples
Parameters
Full name Alias Type Required Help message
--ha-instance -i string no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
 Full name Alias Type Required Help message
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0165E 165 Failed to start job %s: %s.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.

ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
 Exit
Error code code Error message

ZWEL0106E 106 %s parameter is required.

ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
 Exit
Error code code Error message

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe stop
Version: v2.0.x LTS

zwe > stop

Description
Stop Zowe main job.
These Zowe YAML configurations showing with sample values are used:
zowe.setup.security.stcs.zowe is Zowe started task name. This configuration is optional.
Default value is ZWESLSTC .
zowe.jobname is the optional customized job name to start Zowe. If it's empty, the stop command
will try to use value of zowe.setup.security.stcs.zowe as job name to stop.
haInstances.<ha-instance>.sysname is the SYSNAME of the target HA instance. If you pass -
-ha-instance parameter, this is the SYSNAME the start command will be routed to.

Examples
Parameters
Full name Alias Type Required Help message
--ha-instance -i string no

Inherited from parent command

Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
 Full name Alias Type Required Help message
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
ZWEL0166E 166 Failed to stop job %s: %s.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
 Exit
Error code code Error message

ZWEL0106E 106 %s parameter is required.

ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
 Exit
Error code code Error message

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
zwe version
Version: v2.0.x LTS

zwe > version

Description
Display Zowe version.

Examples
Parameters
Inherited from parent command
Full name Alias Type Required Help message
--help -h boolean no
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Error code Exit code Error message
 Error code Exit code Error message
ZWEL0150E 150 Failed to find file %s. Zowe runtimeDirectory is invalid.

Inherited from parent command

Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.
 Exit
Error code code Error message

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.

ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
ZWEL0139E 139 Failed to create directory %s.
ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
 Exit
Error code code Error message

ZWEL0172E Component %s has %s defined but the file is missing.

zwe
Version: v2.0.x LTS

zwe

Sub-commands
certificate
components
init
install
internal
migrate
sample
start
stop
support
version

Description
A command line utility helps you managing Zowe instance.
You can issue --help or -h to find information for all commands it supports.

Examples
Parameters
Full name Alias Type Required Help message
--help -h boolean no
 Full name Alias Type Required Help message
--debug,--verbose -v boolean no
--trace -vv boolean no
--silent -s boolean no
--log-dir,--log -l string no
--config -c string no

Errors
Exit
Error code code Error message

100 If the user pass --help or -h parameter, the zwe command always exits
with 100 code.
ZWEL0101E 101 ZWE_zowe_runtimeDirectory is not defined.
ZWEL0102E 102 Invalid parameter %s.
ZWEL0103E 103 Invalid type of parameter %s.
ZWEL0104E 104 Invalid command %s.
ZWEL0105E 105 The Zowe YAML config file is associated to Zowe runtime "%s", which is not
same as where zwe command is located.
ZWEL0106E 106 %s parameter is required.
ZWEL0107E 107 No handler defined for command %s.
ZWEL0108E 108 Zowe YAML config file is required.
 Exit
Error code code Error message

ZWEL0109E 109 The Zowe YAML config file specified does not exist.
ZWEL0110E 110 Doesn't have write permission on %s directory.
ZWEL0111E 111 Command aborts with error.

ZWEL0112E 112 Zowe runtime environment must be prepared first with "zwe internal start
prepare" command.
ZWEL0120E 120 This command must run on a z/OS system.
ZWEL0121E 121 Cannot find node. Please define NODE_HOME environment variable.
ZWEL0122E 122 Cannot find java. Please define JAVA_HOME environment variable.
ZWEL0123E 123 This function is only available in Zowe Containerization deployment.
ZWEL0131E 131 Cannot find key %s defined in file %s.
ZWEL0132E 132 No manifest file found in component %s.
ZWEL0133E 133 Data set %s already exists.
ZWEL0134E 134 Failed to find SMS status of data set %s.
ZWEL0135E 135 Failed to find volume of data set %s.
ZWEL0136E 136 Failed to APF authorize data set %s.
ZWEL0137E 137 z/OSMF root certificate authority is not provided (or cannot be detected) with
trusting z/OSMF option enabled.
ZWEL0138E 138 Failed to update key %s of file %s.
 Exit
Error code code Error message

ZWEL0139E 139 Failed to create directory %s.

ZWEL0140E 140 Failed to translate Zowe configuration (%s).
ZWEL0142E 142 Failed to refresh APIML static registrations.
ZWEL0172E Component %s has %s defined but the file is missing.
Zowe YAML configuration file reference
Version: v2.0.x LTS

Zowe v2 uses a YAML configuration file during installation, configuration and runtime. This file is usually
referred to as zowe.yaml . YAML is a human-friendly data serialization language for all programming
languages. To learn more about YAML specifications, see https://yaml.org/.
Note: In the following sections, we refer to configuration keys by using concatenation of key names and
dots. For example, if you want to update the configuration key zowe.certificate.keystore.type with
value PKCS12 , you should set value for this entry in the zowe.yaml :
Table of Contents
High-level overview of YAML configuration file
Extract sharable configuration out of zowe.yaml
Configuration override
YAML configurations - certificate
YAML configurations - zowe
YAML configurations - java
YAML configurations - node
YAML configurations - zOSMF
YAML configurations - components
Configure component gateway
Configure component discovery
Configure component api-catalog
Configure component caching-service
Configure component app-server
Configure component zss
Configure component jobs-api
Configure component files-api
Configure component explorer-jes
Configure component explorer-mvs
Configure component explorer-uss
Configure external extension
 YAML configurations - haInstances
Auto-generated environment variables
High-level overview of YAML configuration file
The YAML configuration file has few high-level sections:
zowe
Defines global configurations specific to Zowe, including default values.
java
Defines Java configurations used by Zowe components.
node
Defines node.js configurations used by Zowe components.
zOSMF
Tells Zowe your z/OSMF configurations.
components
Defines detailed configurations for each Zowe component or extension. Each component or extension
may have a key entry under this section. For example, components.gateway is configuration for API
Mediation Layer Gateway service.
haInstances
Defines customized configurations for each High Availability (HA) instance. You should predefine all
Zowe HA instances you want to start within your Sysplex.
Extract sharable configuration out of zowe.yaml
The Zowe YAML configuration file supports a special @include annotation that can be used in any level of
the configuration. This enables you to organize your YAML configuration files and extract sharable
configurations to a separate YAML file.
For example, you can define a sharable certificate configuration file <keystore-dir>/zowe-
certificates.yaml like this:

Then in your zowe.yaml , you can import this certification file like this:
Configuration override
Inside zowe.yaml , you can define default values and they may be overridden in more granular level
configurations. This can happen in several ways:
The component can override the default certificate configuration. For the specific entry of certification
configuration, if it's not overridden, it falls back to default configurations.
Example:
App Server will use the certificate alias app-server instead of localhost from the same keystore
defined in zowe.certificate.keystore.file . And it will use the exact same truststore defined in
zowe.certificate.truststore.file .

Zowe high availability (HA) instance component configuration haInstances.<ha-

instance>.components.<component> can override global level component configurations
components.<component> . Any configuration you can find in components.<component> level
can be overridden in haInstances.<ha-instance>.components.<component> level. For
example, in this configuration:
App Server on lpar2a HA instance will not be started. On lpar2b HA instance, it will be started but
on port 28544.
YAML configurations - certificate
In Zowe YAML configuration, certificate definition shares the same format and this format can be used in
several configuration entries. For example, zowe.certificate , components.
<component>.certificate , and haInstances.<ha-instance>.components.
<component>.certificate . The certificate definition may include the following entries:

keystore.type
Defines the type of the keystore. If you are using keystore, this value usually should be PKCS12 . If you
are using keyring, this value should be JCERACFKS .
keystore.file
Defines the path of the keystore file. If you are using keyring, this should look like
safkeyring:////<keyring-owner>/<keyring-name> . For example,
safkeyring:////ZWESVUSR/ZoweKeyring .

keystore.password
Defines the password of the keystore.
 keystore.alias
Represents the alias name of the certificate stored in keystore. If you are using keyring, this is the
certificate label connected to the keyring.
truststore.type
Defines the type of the truststore file. If you are using keystore, this value usually should be PKCS12 . If
you are using keyring, this value should be JCERACFKS .
truststore.file
Defines the path to the truststore file. If you are using keyring, this should look like
safkeyring:////<keyring-owner>/<keyring-name> , usually will be the same value of
keystore.file .

truststore.password
Defines the password of the truststore.
pem.key
Defines the private key file in PEM format. This can be used by applications that do not support either
PKCS12 keystore format or z/OS keyring.
pem.certificate
Defines the public key file in PEM format. This can be used by applications that do not support either
PKCS12 keystore format or z/OS keyring.
pem.certificateAuthorities
Defines certificate authorities in PEM format. This can be used by applications that do not support
either PKCS12 keystore format or z/OS keyring.
YAML configurations - zowe
The high-level configuration zowe supports these definitions:
Directories
zowe.runtimeDirectory
Tells Zowe the runtime directory where it's installed.
zowe.logDirectory
Some Zowe components write logs to file system. This tells Zowe which directory should be used to
store log files.
zowe.workspaceDirectory Tells Zowe components where they can write temporary runtime files.
 zowe.extensionDirectory
Tells Zowe where you put the runtime of all your extensions.
Zowe Job
zowe.job.name
Defines the Zowe job name for the ZWESLSTC started task.
zowe.job.prefix
Defines the Zowe address space prefix for Zowe components.
Domain and port to access Zowe
zowe.externalDomains
Defines a list of external domains that will be used by the Zowe instance. This configuration is an array
of domain name strings. In Sysplex deployment, this is the DVIPA domain name defined in Sysplex
Distributor. For example,
In Kubernetes deployment, this is the domain name you will use to access your Zowe running in
Kubernetes cluster.
zowe.externalPort
Defines the port that will be exposed to external Zowe users. By default, this value is set based on Zowe
APIML Gateway port. In Sysplex deployment, this is the DVIPA port defined in Sysplex Distributor. See
Configure Sysplex Distributor for more information. In Kubernetes deployment, this is the gateway
Service port will be exposed to external.
Extra environment variables
zowe.environments
Defines extra environment variables to customize the Zowe runtime. This configuration is a list of key /
value pairs. Example:
Please be aware that variables defined here are global to all Zowe components, on all HA instances.
Certificate
zowe.certificate
Defines the northbound certificate facing Zowe users.
zowe.verifyCertificates Defines how Zowe should validate the certificates used by
components or external service(s) like z/OSMF. It can be a value of:
 STRICT : This is the default value. Zowe will validate if the certificate is trusted in our trust store
and if the certificate Command Name and Subject Alternative Name (SAN)is validated. This is
recommended for the best security.
NONSTRICT : Zowe will validate if the certificate is trusted in our trust store. In this mode, Zowe
does not validate certificate Common Name and Subject Alternative Name (SAN). This option does
not have the best security but allows you to try out Zowe when you don't have permission to fix
certificate used by external services like z/OSMF.
DISABLED : This will disable certificate validation completely. This is NOT recommended for
security purpose.
Launcher and launch scripts
Launcher is the program behind ZWESLSTC started task.
zowe.launcher
The launcher section defines defaults about how the Zowe launcher should act upon components.
zowe.launcher.restartIntervals
An array of positive integers that defines how many times a component should be tried to be restarted if
it fails, and how much time to wait in seconds for that restart to succeed before retrying.
zowe.launcher.minUptime
The minimum amount of time a zowe component should be running in order to be declared as started
successfully.
zowe.launcher.shareAs
Whether or not the launcher should start components in the same address space as it. See
documentation for _BPX_SHAREAS for details.
zowe.launchScript.logLevel You can set it to debug or trace to enable different level of
debug messages from Zowe launch scripts. This may help to troubleshoot issues during Zowe start.
Setup
Zowe YAML configuration uses zowe.setup section to instruct how Zowe should be installed and
configured. This section is optional for Zowe runtime but only be used for zwe install and zwe init
commands.
zowe.setup.dataset.prefix shows where the SZWEAUTH data set is installed.

zowe.setup.dataset.parmlib is the user custom parameter library. Zowe server command may
generate sample PARMLIB members and stores here.
zowe.setup.dataset.jcllib is the custom JCL library. Zowe server command may generate
sample JCLs and put into this data set.
zowe.setup.dataset.authLoadlib is the user custom APF LOADLIB. This field is optional. If this
is defined, members of SZWEAUTH will be copied over to this data set and it will be APF authorized. If
it's not defined, SZWEAUTH from zowe.setup.dataset.prefix will be APF authorized.
zowe.setup.dataset.authPluginLib is the user custom APF PLUGINLIB. You can install Zowe
ZIS plug-ins into this load library. This loadlib requires APF authorize.
zowe.setup.security.product is security product. Can be RACF , ACF2 , or TSS . This
configuration is optional. Default value is RACF .
zowe.setup.security.groups.admin is the group for Zowe administrators. This configuration is
optional. Default value is ZWEADMIN .
zowe.setup.security.groups.stc is the group for Zowe started tasks. This configuration is
optional. Default value is ZWEADMIN .
zowe.setup.security.groups.sysProg is system programmer user ID/group. This configuration
is optional. Default value is ZWEADMIN .
zowe.setup.security.users.zowe is the userid for Zowe started task. This configuration is
optional. Default value is ZWESVUSR .
zowe.setup.security.users.zis is userid for ZIS started task. This configuration is optional.
Default value is ZWESIUSR .
zowe.setup.security.stcs.zowe is Zowe started task name. This configuration is optional.
Default value is ZWESLSTC .
zowe.setup.security.stcs.zis is ZIS started task name. This configuration is optional. Default
value is ZWESISTC .
zowe.setup.security.stcs.aux is ZIS AUX started task name. This configuration is optional.
Default value is ZWESASTC .
zowe.setup.certificate.type is the type of certificate. Valid values are PKCS1 (USS keystore)
or JCERACFKS (z/OS keyring).
 zowe.setup.certificate.dname is the distinguished name of the certificate. You can define
caCommonName , commonName , orgUnit , org , locality , state , and / or country .
These configurations are optional.
zowe.setup.certificate.validity is the validity days of the certificate. This is optional.

zowe.setup.certificate.san is the Subject Alternative Name (s) of the certificate if they

are different from zowe.externalDomains . Note that for JCERACFKS type, with limitation of
RACDCERT command, this should contain exact one hostname (domain) and one IP address.
zowe.setup.certificate.importCertificateAuthorities is the list of certificate authorities
will be imported to Zowe PKCS12 keystore or JCERACFKS keyring. Please note, for JCERACFKS
type, only maximum 2 CAs is supported. If you are using PKCS12 certificate, this should be USS files
in PEM format. If you are using JCERACFKS certificate, this should be certificate labels on the z/OS
system.
For PKCS12 certificate users,
zowe.setup.certificate.pkcs12.directory is the directory where you plan to store the
PKCS12 keystore and truststore. This is required if zowe.setup.certificate.type is PKCS12 .
zowe.setup.certificate.pkcs12.lock is a boolean configuration to tell if we should lock the
PKCS12 keystore directory only for Zowe runtime user and group. Default value is true.
You can also define name , password , caAlias and caPassword under
zowe.setup.certificate.pkcs12 to customized keystore and truststore. These configurations
are optional, but it is recommended to update them from default values.
Define zowe.setup.certificate.pkcs12.import.keystore if you already acquired certificate
from other CA, stored them in PKCS12 format, and want to import into Zowe PKCS12 keystore.
zowe.setup.certificate.pkcs12.import.password is the password for keystore defined in
zowe.setup.certificate.pkcs12.import.keystore .

zowe.setup.certificate.pkcs12.import.alias is the original certificate alias defined in

zowe.setup.certificate.pkcs12.import.keystore . After imported, the certificate will be
saved as alias specified in zowe.setup.certificate.pkcs12.name .
For JCERACFKS certificate (z/OS keyring) users,
zowe.setup.certificate.keyring.owner is the keyring owner. It's optional and default value is
zowe.setup.security.users.zowe . If it's also not defined, the default value is ZWESVUSR .
zowe.setup.certificate.keyring.name is the keyring name will be created on z/OS. This is
required if zowe.setup.certificate.type is JCERACFKS .
If you want to let Zowe to generate new certificate,
You can also customize label and caLabel under zowe.setup.certificate.keyring if
you want to generate new certificate. Default value of label is localhost and default value of
caLabel is localca .

If you want to import certificate stored in MVS data set into Zowe keyring,
zowe.setup.certificate.keyring.connect.dsName is required in this case. It tells Zowe
the data set where the certificate stored.
zowe.setup.certificate.keyring.connect.password is the password when importing
the certificate.
The certificate will be imported with label defined in
zowe.setup.certificate.keyring.label .

If you want to connect existing certificate into Zowe keyring,

zowe.setup.certificate.keyring.connect.user is required and tells Zowe the owner of
existing certificate. This field can have value of SITE .
zowe.setup.certificate.keyring.connect.label is also required and tells Zowe the
label of existing certificate.
If zowe.verifyCertificates is not DISABLED , and z/OSMF host ( zOSMF.host ) is provided,
Zowe will try to trust z/OSMF certificate.
If you are using RACF security manager, Zowe will try to automatically detect the z/OSMF CA
based on certificate owner specified by zowe.setup.certificate.keyring.zOSMF.user .
Default value of this field is IZUSVR . If the automatic detection failed, you will need to define
zowe.setup.certificate.keyring.zOSMF.ca indicates what is the label of z/OSMF root
certificate authority.
If you are using ACF2 or TSS (Top Secret) security manager,
zowe.setup.certificate.keyring.zOSMF.ca is required to indicates what is the label of
z/OSMF root certificate authority.
zowe.setup.vsam.mode indicates whether the VSAM will utilize Record Level Sharing (RLS)
services or not. Valid value is RLS or NONRLS .
 zowe.setup.vsam.volume indicates the name of volume. This field is required if VSAM mode is
NONRLS .
zowe.setup.vsam.storageClass indicates the name of RLS storage class. This field is required if
VSAM mode is RLS .
YAML configurations - java
The high-level configuration java supports these definitions:
home
Defines the path to the Java runtime directory.
YAML configurations - node
The high-level configuration node supports these definitions:
home
Defines the path to the Node.js runtime directory.
YAML configurations - zOSMF
The high-level configuration zOSMF supports these definitions:
zOSMF.host
Defines the hostname of your z/OSMF instance.
zOSMF.port
Defines the port of your z/OSMF instance.
zOSMF.applId
Defines the application ID of your z/OSMF instance.
YAML configurations - components
All Zowe components and extensions can have a dedicated section under the components high-level
configuration.
In this section, <component> represents any Zowe components or extensions. For all components and
extensions, these are the common definitions.
 components.<component>.enabled
Defines if you want to start this component in this Zowe instance. This allows you to control each
component instead of a group.
components.<component>.certificate
You can customize a component to use different certificate from default values. This section follows
same format defined in YAML configurations - certificate. If this is not customized, the component will
use certificates defined in zowe.certificate .
components.<component>.launcher
Any component can have a launcher section which overrides the overall Zowe Launcher default defined
in zowe.launcher .
Configure component gateway
These configurations can be used under the components.gateway section:
port
Defines the port which the gateway should be started on. This must be a valid port number.
debug
Defines whether to enable debug mode for the Gateway.
apiml.service.allowEncodedSlashes
When this parameter is set to true , the Gateway allows encoded characters to be part of URL
requests redirected through the Gateway.
apiml.service.corsEnabled
When this parameter is set to true , CORS are enabled in the API Gateway for Gateway routes
gateway/api/v1/** .

apiml.service.preferIpAddress
Set this parameter to true to advertise a service IP address instead of its hostname. Note: This
configuration is deprecated. Zowe start script will ignore this value and always set it to false .
apiml.gateway.timeoutMillis
Specifies the timeout for connection to the services in milliseconds.
apiml.security.x509.enabled
Set this parameter to true to enable the client certificate authentication functionality through ZSS.
apiml.security.x509.externalMapperUrl
Defines the URL where Gateway can query the mapping of client certificates.
apiml.security.auth.provider
Defines the authentication provider used by the API Gateway.
 apiml.security.authorization.endpoint.url
Defines the URL to the authorization endpoint. This endpoint tells Gateway if a user has a particular
permission on SAF profile. For example, permission to the APIML.SERVICES profile of ZOWE class.
apiml.security.ssl.verifySslCertificatesOfServices
Defines whether APIML should verify certificates of services in strict mode. Setting to true will
enable the strict mode where APIML will validate if the certificate is trusted in turststore, and also if
the certificate Common Name or Subject Alternate Name (SAN) matches the service hostname.
apiml.security.ssl.nonStrictVerifySslCertificatesOfServices
Defines whether APIML should verify certificates of services in non-strict mode. Setting the value to
true will enable the non-strict mode where APIML will validate if the certificate is trusted in
turststore, but ignore the certificate Common Name or Subject Alternate Name (SAN) check. Zowe will
ignore this configuration when strict mode is enabled with
apiml.security.ssl.verifySslCertificatesOfServices .

apiml.server.maxConnectionsPerRoute
Specifies the maximum connections for each service.
apiml.server.maxTotalConnections
Specifies the total connections for all services registered under API Mediation Layer.
Configure component discovery
These configurations can be used under the components.discovery section:
port
Defines the port which discovery should be started on. This may be defined as a valid port number or as
an offset from the Gateway component's port. To define an offset enter "+{offset}" or "-
{offset}" as a string. The offset must start with + or - .

debug
Defines whether to enable debug mode for the Discovery Service.
apiml.service.preferIpAddress
Set this parameter to true to advertise a service IP address instead of its hostname. Note: This
configuration is deprecated. The Zowe start script will ignore this value and always set it to false .
apiml.security.ssl.verifySslCertificatesOfServices
Defines whether APIML should verify certificates of services in strict mode. Setting to true will
enable the strict mode where APIML will validate both if the certificate is trusted in turststore, and
also if the certificate Common Name or Subject Alternate Name (SAN) matches the service hostname.
 apiml.security.ssl.nonStrictVerifySslCertificatesOfServices
Defines whether APIML should verify certificates of services in non-strict mode. Setting to true will
enable the non-strict mode where APIML will validate if the certificate is trusted in turststore, but
ignore the certificate Common Name or Subject Alternate Name (SAN) check. Zowe will ignore this
configuration if strict mode is enabled with
apiml.security.ssl.verifySslCertificatesOfServices .

alternativeStaticApiDefinitionsDirectories
Specifies the alternative directories of static definitions.
apiml.server.maxTotalConnections
Specifies the total connections for all services registered under API Mediation Layer.
apiml.discovery.serviceIdPrefixReplacer
Modifies the service ID of a service instance before it registers to API Mediation Layer. Using this
parameter ensures compatibility of services that use a non-conformant organization prefix with v2,
based on Zowe v2 conformance.
Configure component api-catalog
These configurations can be used under the components.api-catalog section:
port
Defines the port which API Catalog should be started on.
debug
Defines if we want to enable debug mode for the API Catalog. This is equivalent to the
APIML_DEBUG_MODE_ENABLED variable but with better granular level.

environment.preferIpAddress
Set this parameter to true to advertise a service IP address instead of its hostname.
Note: This configuration is deprecated. Zowe start script will ignore this value and always set it to
false .

Configure component caching-service

These configurations can be used under the components.caching-service section:
port
Defines the port which Caching Service should be started on. This may be defined as a valid port
number or as an offset from the Gateway component's port. To define an offset enter "+{offset}"
or "-{offset}" as a string. The offset must start with + or - .
debug
Defines if we want to enable debug mode for the Caching Service.
storage.mode
Sets the storage type used to persist data in the Caching Service.
storage.size
Specifies amount of records before eviction strategies start evicting.
storage.evictionStrategy
Specifies eviction strategy to be used when the storage size is achieved.
storage.vsam.name
Specifies the data set name of the caching service VSAM data set.
storage.redis.masterNodeUri
Specifies the URI used to connect to the Redis master instance in the form
username:password@host:port .

storage.redis.timeout
Specifies the timeout second to Redis. Defaults to 60 seconds.
storage.redis.sentinel.masterInstance : Specifies the Redis master instance ID used by the
Redis Sentinel instances.
storage.redis.sentinel.nodes
Specifies the array of URIs used to connect to a Redis Sentinel instances in the form
username:password@host:port .

storage.redis.ssl.enabled
Specifies the boolean flag indicating if Redis is being used with SSL/TLS support. Defaults to true .
storage.redis.ssl.keystore
Specifies the keystore file used to store the private key.
storage.redis.ssl.keystorePassword
Specifies the password used to unlock the keystore.
storage.redis.ssl.truststore
Specifies the truststore file used to keep other parties public keys and certificates.
storage.redis.ssl.truststorePassword
Specifies the password used to unlock the truststore.
environment.preferIpAddress
Set this parameter to true to advertise a service IP address instead of its hostname. Note: this
configuration is deprecated. Zowe start script will ignore this value and always set it to false .
 apiml.security.ssl.verifySslCertificatesOfServices
Specifies whether APIML should verify certificates of services in strict mode. Set to true will enable
strict mode that APIML will validate both if the certificate is trusted in turststore, and also if the
certificate Common Name or Subject Alternate Name (SAN) match the service hostname.
apiml.security.ssl.nonStrictVerifySslCertificatesOfServices
Defines whether APIML should verify certificates of services in non-strict mode. Setting to true will
enable non-strict mode where APIML will validate if the certificate is trusted in turststore, but
ignore the certificate Common Name or Subject Alternate Name (SAN) check. Zowe will ignore this
configuration if strict mode is enabled with
apiml.security.ssl.verifySslCertificatesOfServices .

Configure component app-server

These configurations can be used under the components.app-server section:
port
Defines the port which App Server should be started on. This may be defined as a valid port number or
as an offset from the Gateway component's port. To define an offset enter "+{offset}" or "-
{offset}" as a string. The offset must start with + or - .

Configure component zss

These configurations can be used under the components.zss section:
port
Defines the port which ZSS should be started on. This may be defined as a valid port number or as an
offset from the Gateway component's port. To define an offset enter "+{offset}" or "-
{offset}" as a string. The offset must start with + or - .

Configure component jobs-api

These configurations can be used under the components.jobs-api section:
port
Defines the port which Jobs API should be started on. This may be defined as a valid port number or as
an offset from the Gateway component's port. To define an offset enter "+{offset}" or "-
{offset}" as a string. The offset must start with + or - .
 debug
Defines whether to enable debug logging for the Jobs API.
Configure component files-api
These configurations can be used under the components.files-api section:
port
Defines the port which Files API should be started on. This may be defined as a valid port number or as
an offset from the Gateway component's port. To define an offset enter "+{offset}" or "-
{offset}" as a string. The offset must start with + or - .

debug
Defines whether to enable debug logging for the Files API.
Configure external extension
You can define a components.<extension-id> section and use common component configuration
entries.
For example, enable my-extension :
YAML configurations - haInstances
All Zowe high availability instances should have a dedicated section under the haInstances high-level
configuration.
In this section, <ha-instance> represents any Zowe high availability instance ID.
For all high availability instances, these are the common definitions.
haInstances.<ha-instance>.hostname
Defines the host name where you want to start this instance. This could be the host name of one LPAR
in your Sysplex.
haInstances.<ha-instance>.sysname
Defines the system name of the LPAR where the instance is running. Zowe will use ROUTE command
to send JES2 start or stop command to this HA instance.
haInstances.<ha-instance>.components.<component>
Optional settings you can override component configurations for this high availability instance. See
 Configuration override for more details.
Auto-generated environment variables
Each line of Zowe YAML configuration will have a matching environment variable during runtime. This is
converted based on pre-defined pattern:
All configurations under zowe , components , haInstances will be converted to a variable with
name:
prefixed with ZWE_ ,
any non-alphabetic-numeric characters will be converted to underscore _ ,
and no double underscores like __ .
Calculated configurations of haInstance , which is portion of haInstances.<current-ha-
instance> will be converted same way.

Calculated configurations of configs , which is portion of haInstances.<current-ha-

instance>.components.<current-component> will be converted same way.

All other configuration entries will be converted to a variable with name:

all upper cases,
any non-alphabetic-numeric characters will be converted to underscore _ ,
and no double underscores like __ .
For examples:
ZWE_zowe_runtimeDirectory , parent directory of where zwe server command is located.

ZWE_zowe_workspaceDirectory is the path of user customized workspace directory.

ZWE_zowe_setup_dataset_prefix is the high-level qualifier where Zowe MVS data sets are
installed.
ZWE_zowe_setup_dataset_parmlib is the data set configured to store customized version of
parameter library members.
ZWE_zowe_setup_dataset_authPluginLib is the data set configured to store APF authorized ZIS
plug-ins load library.
ZWE_zowe_setup_security_users_zowe is the name of Zowe runtime user.

ZWE_configs_port is your component port number you can use in your start script. It points to the
value of haInstances.<current-ha-instance>.components.<your-component>.port , or
fall back to components.<my-component>.port , or fall back to configs.port defined in your
component manifest.
Server component manifest file reference
Version: v2.0.x LTS

Zowe server component manifest file defines the name and purpose of the component. It also provides
information about how this component should be installed, configured, and started. It can be named as
manifest.yaml , manifest.yml , or manifest.json and should be located in the root directory of
the component. Currently, only YAML or JSON format are supported.
The manifest file contains the following properties:
name

(Required) Defines a short, computer-readable name of the component. This component name is used
as directory name after it is installed. The allowed characters in the name are alphabets, numbers,
hyphen ( - ) and underscore ( _ ). For example, explorer-jes is a valid extension name.
id

(Optional) Defines a long, computer-readable identifier of the component. If the component is hosted
as one of the projects in Open Mainframe Project, the identifier also matches the component path in the
Zowe Artifactory. For example, org.zowe.explorer-jes is a valid identifier. You can locate the
component's official releases by looking into the libs-release-local/org/zowe/explorer-
jes/ directory in the Zowe Artifactory.

version :

(Optional but recommended) This is the current version of the component without the prefix of v . For
example, 2.0.0 is a valid version value.
title

(Optional) Defines a short human-readable name for this component. This value will also be used as the
default title for API Catalog tile, or App Framework plug-in title. For example, JES Explorer is a valid
title for the explorer-jes component.

description

(Optional) Defines a long human-readable description of this component. There is no restriction on

what you can put in the field.
license

(Optional but recommended) Defines the license code of the component. For example, Zowe core
components have EPL-2.0 value in this field.
schemas

(Required) Defines the location of json schema files that are compatible with certain portions of Zowe
as denoted by each child property.
configs

(Required) Defines the location of the json schema file which extends the Zowe Component base
schema.
build

(Optional but strongly recommended) Defines the build information of the current package, including git
commit hash, and so on. When Zowe core components define manifest file, these fields are left as
template variables. The template will be updated when a publishable package is created. It supports the
following subfields:
branch

It indicates which branch this package is built from.

number

You may create multiple packages in the same branch. This is the sequential number of the current
package.
commitHash

This is the commit hash of the package that can be used to match the exact source code in the
repository. Zowe core components usually use git rev-parse --verify HEAD to retrieve the
commit hash.
timestamp

This is the UNIX timestamp when the package is created.

commands

This defines actions that should be taken when the component is installed, configured, started, or
tested. You must issue this command with one or more subfields as listed below. For example,
commands.install . All subfields are optional and usually should point to a USS command or script.

install

This defines extra steps when installing this component. It will be automatically executed if you
install your component with the zwe components install server command.
validate

This defines extra validations that the component requires other than global validations. It is for
runtime purpose, and will be automatically executed each time Zowe is started.
configure

This defines extra configuration steps before starting the component. It is for runtime purpose, and
will be automatically executed each time Zowe is started.
start

This tells the Zowe launch script how to start the component. It is for runtime purpose, and will be
automatically executed each time Zowe is started.
apimlServices

This section defines how the component will be registered to the API Mediation Layer Discovery
Service. All subfields are optional.
dynamic

Array of objects. This information will tell Zowe and users what services you will register under the
Discovery service.
serviceId

This defines the service ID registered to the Discovery service.

static
 Array of objects. When the component is statically registered under the Discovery service, this tells
Zowe where to find these static definitions. This information is for the Zowe runtime. When Zowe is
starting, the launch script will check this field and put the parse static definition file into the
directory defined as ZWE_STATIC_DEFINITIONS_DIR in the Zowe instance.
file

Defines the path to the static definition file. This file is supposed to be a template.
basePackage

Defines the base package name of the extension. It is used to notify the extended service of
the location for component scan.
appfwPlugins

Array of objects. This section defines how the component will be registered to the App Framework
plug-in. All subfields are optional.
path

This points to the directory where App Framework pluginDefinition.json file is located.
When Zowe is starting, the launch script will check this field and register the plug-in to Zowe App
Framework Server.
gatewaySharedLibs : Array of objects. This section defines the API ML extension(s) attributes which
will get installed and used by API ML.
path

This points to the directory where the JAR files are housed for an extension and later on copied into
the API ML extensions workspace directory. If there is more than 1 extension to a single manifest
(say for a product family of multiple extensions), then multiple path variables can be contained
within the manifest denoted by individual folders, for example path/to/yourextension1/ .
Alternatively, path can be the JAR file path rather than a directory path.
zisPlugins

List of ZIS plugin objects. This section defines the ZIS plugin(s) attributes necessary for ZIS plugin
installation and automation.
 id

This is the unique plugin ID of the ZIS plugin.

path

This points to the directory where the load modules are housed for a plugin, for example
/zisServer . If there is more than 1 plugin to a single manifest (say for a product family of
multiple plugins), then multiple path variables can be contained within the manifest denoted by
individual folders, for example yourplugin1/zisServer . The parameters for the Zowe parmlib
are assumed to be in <PATH>/samplib . The names of the plugin executables are assumed to be
in <PATH>/loadlib .
For example,
configs

Component can define it's own configuration in this section in desired hierarchy. This is the brief
guidance for component user to learn what are the configurations and what are the default values. Any
configurations defined here can be placed into zowe.yaml components.<component-name>
section for customization.
For example, if the component has this defined in component manifest,
You can choose to put those configurations into components.myextension or haInstance.<ha-
instance>.components.myextension of zowe.yaml like this:

Component can use auto-generate environment variables in lifecycle scripts to learn how the
component is configured for current HA instance. In the preceding use case,
For HA instance lpar1 , ZWE_configs_port value is 14567 ,
ZWE_configs_another_config value is my-value , which are default values.

For HA instance lpar2 , ZWE_configs_port value is 24567 ,

ZWE_configs_another_config value is my-value2 .

From another component, you can find myextension configurations like this,
For HA instance lpar1 , ZWE_components_myextension_port value is 14567 ,
ZWE_components_myextension_another_config value is my-value , which are default
values.
 For HA instance lpar2 , ZWE_components_myextension_port value is 24567 ,
ZWE_components_myextension_another_config value is my-value2 .

Note: All paths of directories or files mentioned previously should be relative paths to the root directory
where manifest is located.
Bill of Materials
Version: v2.0.x LTS

Zowe™ uses the SPDX SBOM format to represent its bill of materials. To read more about why SBOMs and
SPDX are used, see this blog. The hash codes can be used to validate your download is authentic using a
command like openssl dgst -sha1 <downloaded_sbom.zip> . Zowe SBOMs are as follows:

Type Component SBOM SHA-1 Hash

Link
Artifact Zowe z/OS Components SBOM 3ed80afaadfdabe1112c7063fe297d5f
SBOM (PAX, SMP/E, PSWI) Link
Artifact Zowe CLI Standalone SBOM 98b75ca32cc08664574da1886d28c625463cceba
SBOM Package Link
Artifact Zowe CLI Standalone SBOM 7d1e06e579b4dcc69c44405a47dfebc386426b0f
SBOM Plugins Package Link
Artifact Zowe Client NodeJS SBOM c61bd6b9f78ba2aa67a0f4e53874a097992d8155
SBOM SDK Link
Artifact Zowe Client Python SDK SBOM
SBOM Link 637c5f90f94a88cb534bead7755fac112b509217
Source All Zowe's Source SBOM 19d2b81b0fa2955d165123871c72c2c77ddf73b7
Code Repositories used in Link
SBOM final artifacts