Planning the installation

The following information is required during the 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 zFS directory that is known as an instance directory.

• For Zowe in a high availability configuration, there will be only one instance directory which must be created on a shared file system (zFS directory) where all LPARs in a Sysplex can access. To install Zowe in a Parallel Sysplex environment, a YAML configuration file is used to customize the Zowe high availability instances.

• (If not using Docker) Zowe uses a zFS directory to contain its northbound certificate keys as well as a truststore for its southbound keys. 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

  • ZWESVSTC 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 Docker likely only ZSS will be used here.

  • ZWESLSTC is used for Zowe high availability configuration rather than ZWESVSTC. It brings up and stops Zowe high availability instances, or specific Zowe components without restarting the entire Zowe high availability 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 ZWESVSTC. 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 ZWESVSTC.

Topology of the Zowe z/OS launch process

The following diagram depicts the high-level structure of a Zowe installation and runtime.

RUNTIME_DIR

The runtime directory <RUNTIME_DIR> contains the binaries and executable files. You can create a runtime directory in one of the following ways:

• Executing the zowe-install.sh script contained within the install directory of a Zowe convenience build.
• Installing the Zowe SMP/E FMID AZWE001 using the JCL members in the REL4 member.
• Executing the z/OSMF worklow script ZWERF01 contained in the SMP/E FMID AZWE001.

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.

INSTANCE_DIR

The instance directory <INSTANCE_DIR> is required to launch Zowe. It is created with the script <RUNTIME_DIR>/bin/zowe-configure-instance.sh. More than one instance directory can be created and used to launch multiple instances of Zowe sharing the same runtime directory <RUNTIME_DIR>.

Zowe instances are started by running the script <INSTANCE_DIR>/bin/zowe-start.sh. This creates a started task with the PROCLIB member ZWESVSTC that is provided with the samplib SZWESAMP created during the installation of Zowe. The JCL member ZWESVSTC starts a USS shell under which it launches its address spaces.

The instance directory file instance.env is used to configure a Zowe launchable. The file is executed during the launch of Zowe and specifies shell variables such as ports and location of dependent directories and services on z/OS.

The instance.env file sets the location of the <RUNTIME_DIRECTORY> as well as the <KEYSTORE_DIRECTORY>

Note: Alternatively, from v1.22.0 release, you can use a YAML format configuration file zowe.yaml instead of instance.env to configure the Zowe runtime for high availability. To learn more about the zowe.yaml file, see Updating the zowe.yaml configuration file.

KEYSTORE_DIRECTORY

Zowe uses certificates to encrypt data as well as a truststore. The keystore directory <KEYSTORE_DIRECTORY> controls where the certificates are located, either in a JavaKeystore or a z/OS keyring. A <KEYSTORE_DIRECTORY> is created by using the script <RUNTIME_DIR>/bin/zowe-setup-certificates.sh.