Installing Zowe on z/OS

[{Core}] The Open Mainframe Project’s Zowe delivers its software in three main pieces.

• Command line interface (CLI) that provides a command driven interface for common z/OS tasks like working with files and jobs as well as issuing TSO and console commands. The CLI runs anywhere that node.js runs, typically on a laptop such as a user’s PC or Mac, a devops pipeline client, as well as z/OS with node itself. As well as core function the CLI is also an extensible platform supporting plugins that extend its endpoints to include additional z/OS subsystems such as CICS, DB2, MQas well as vendor extensions covering, CA Endeavor, IBM z/OS Connect, Phoenix Software EJES, and more.
• Zowe Explorer that is a Visual Studio extension. It uses the same code that underpins the Zowe CLI to connect to z/OS, and provides a rich graphical user interface to work with data sets, Unix files, and the JES subsystem. More information is available on the Visual Studio marketplace.
• A z/OS component that contains the Zowe Web Desktop, the Zowe API Mediation Layer, and a number of Zowe applications such as a 3270 emulator and rich GUIs for working with data sets, Unix files and the JES subsystem that can be accessed through a web browser. As well as providing core apps, the Zowe Web Desktop is a framework that can be extended through plugins and extensions.

This blog is a walk through of an installation, configuration and launch of the z/OS component. For the other Zowe components see Installing Zowe CLI, and Zowe Explorer in Visual Code.

This blog describes how to install version 1.9 of Zowe which is the beginning of the active long term support (LTS) release. If the install changes significantly with subsequent release of Zowe version 1 I’ll keep this blog updated, however no major changes are planned for version 1 so if you are installing Zowe 1.10, 1.11 and so forth the instructions should remain relevant.

Download

To get started you’ll need to have a build os Zowe which is available on https://zowe.org. There is a Downloads section with a button labelled Zowe v.r.m z/OS Components that triggers your browser to download a zowe-v.r.m.pax file. The v refers to the version of Zowe, which is currently version 1. The r is the release number and is increased each time a monthly rollup driver is created. The m is the modification number and will be incremented if a specific mid month build is needed, for example to address a critical defect that the community wishes to get in the hands of users before the rollup release is finished.

Zowe is also available to install in SMP/e format which I’ll blog about later. The .pax file and SMP/e differ in how they lay down their files on disk, but the configuration steps are the same.

Transfer to z/OS

The zowe-1.9.0.pax file needs to be moved from your desktop download folder to a z/OS USS directory. There are a number of ways to get the file onto USS and for my system I’m using secure file transfer protocol.

After the zowe-1.9.0.pax file has transferred USS the next step is to exit sftp and use ssh to connect

Expand the zowe.pax file

From within the directory where you uploadedzowe-1.9.0.pax , expand its contents using the command pax -ppx -rf zowe-1.9.0.pax . After this you will have a new directory zowe-1.9.0 that contains the expanded contents of the pax file.

Run zowe-install.sh to create the runtime folder and data sets

In the zowe-1.9.0/install directory run zowe-install.sh to create a USS directory containing the runtime Zowe files, as well as a PDS SAMPLIB and AUTHLIB. The script zowe-install.sh has two arguments for the location of where these should be created.

• -h <PDS_PREFIX> the PDS HLQ prefix to be used for the PDS members.
• -i <ROOT_DIR> for where the Zowe runtime code should be installed into a USS directory

In the screen shot below I have used WINCHJ.ZWE190 as my PDS prefix, and u/winchj/zowe-1.9.0/runtime as the location for my runtime directory. The install script writes its progress to the console. Detailed messages are written to a log folder that is useful to debug issues that may occur with the script.

v

After zowe-install.sh has run successfully there will be two new PDS members. The PDS SZWEAUTHis a load library and contains two load modules, the cross memory server and the auxiliary server. More about these later. The PDS SZWESAMP is fixed block 80 containing text files. This includes the JCL for the PROCLIBs used to start Zowe, as well as an important z/OS environment preparation JCL fileZSWESECUR

If you had installed Zowe prior to 1.9 you would have had to edit a file zowe-install.yaml containing all of Zowe’s configuration data such as ports, and the script would have validated pre-requisites such as Java, node, or z/OSMF. Note that this is no longer done at install time which just creates a USS <RUNTIME_DIR> directory and two PDS members. Configuration data is specified at launch time (see Create a Zowe instance directory below).

Prepare the z/OS environment for Zowe with ZWESECUR (one time only)

The z/OS environment needs to be configured in order to run Zowe. I won’t go into detail in this blog post as configuring a z/OS environment should be done by an experienced z/OS system programmer and has variants for every site based on local rules and settings. A full description is included in the documentation chapter Configuring the z/OS System for Zowe. Key points is that a JCL member ZWESECUR is provided that is executable JCL containing many MVS commands as configuration steps. It can be customized to run for specific security managers by setting the PRODUCT variable.

//         SET PRODUCT=RACF          * RACF, ACF2, or TSS

Installing the Zowe started task ZWESVSTC

When Zowe executes it runs the started task ZWESVSTC . For this to occur the JCL member for this is delivered in the SZWESAMP file must be a member of a PDS that is in the JES concatenation path. This can be done manually or else with a convenience script <RUNTIME_DIR>/scripts/utils/zowe-install-proc.sh . More detail is available in the documentation chapter Installing the Zowe started task.

Installing and configuring the Zowe cross memory server ZWESISTC

Zowe provides a number of secure services in a load module ZWESIS01 that runs APF authorized key(4) non-swappable. It is run under the started task ZWESISTC. It is used by the Zowe desktop for tasks such as authenticating user IDs and tasks that required elevated levels of z/OS privilege. All of Zowe’s other microservices communicate with each other through socket connections, except for ZWESIS01 where the conversation from the desktop is made via a cross memory connection, hence its name cross memory server.

If you only intend to use the API Mediation Layer you can skip installing the cross memory server. (Detail on how to start Zowe with just the mediation layer and not the desktop is controlled by the LAUNCH_COMPONENT_GROUPS parameter covered below in section The instance.env file).

For more information on how to install and configure the cross memory server see the documentation chapter Zowe cross memory server (ZWESISTC) as well as the blog post Configuring the Cross Meory Server. https://medium.com/p/a5b86cc6981b

Create a Zowe keystore directory (one-time only)

A keystore directory is used by Zowe to hold the certificate used for encrypting communication between Zowe clients and the Zowe z/OS servers. This directory also holds the trust store used to hold public keys of any servers that Zowe communicates to itself as a client. Before Zowe can be launched a keystore directory needs to created, see the documentation chapter Configuring Zowe certificates for more detail.

If you are creating a keystore directory you should first copy the file <RUNTIME_DIR>/bin/zowe-setup-certificates.env to a local directory. Edit the file to specify the location of the keystore directory you wish to generate by updating the KEYSTORE_DIRECTORY path value.

# Location for generated certificates
KEYSTORE_DIRECTORY=/u/winchj/zowe-keys

There are additional values that can be edited in the zowe-setup-certificates.env file. Another common one that should be edited is VERIFY_CERTIFICATE . This controls whether the API Mediation Layer should trust servers that present untrusted certificates. In many z/OS sites the z/OSMF certificate is self signed and will be rejected by default when the API Mediation Layers connects to it, and in that case the value should be updated

# Should APIML verify certificates of services it uses - true/false
VERIFY_CERTIFICATES=false

Create a Zowe instance directory

Before launching Zowe you will need to create an instance directory. A Zowe runtime directory should be thought of as read only. When a new version of Zowe is installed it will replace the previous runtime, this is especially true with SMP/E PTFs that will be covered in a separate blogpost. The instance directory contains data that is expected to be edited at a Zowe installation prior to launching such as ports, location of pre-requisites such as Java or Node, and it also contains writeable data such as log files. The instance directory also contains locations of Zowe extensions.

To create an instance directory run the script <RUNTIME_DIR>/bin/zowe-configure-instance.sh . This has a -c parameter for the location to create the instance directory in. Choose a location that is outside of the RUNTIME_DIR .

A Zowe instance directory contains the file instance.env that is a list of configuration parameters used to control Zowe such as port numbers and address space names, as well as a script /bin/zowe-start.sh to launch Zowe and /bin/zowe-stop.sh to stop Zowe. More than one instance directory can be created from a Zowe runtime directory and can be launched independently.

Before launching Zowe you will likely need to edit some of the values in the instance.env file to control how your Zowe will run.

The KEYSTORE_DIRECTORY value in instance.env points to the path of the Zowe keystore directory. This should be changed to match the keystore directory generated using zowe-setup-certificates.sh created in the section Create a Zowe keystore directory (one time only) described earlier.

KEYSTORE_DIRECTORY=/u/winchj/zowe-keys

The LAUNCH_COMPONENT_GROUPS value controls which components should be started. By default both the API Mediation Layer and the Zowe desktop address spaces are started, however you can modify the value to only launch one of the subsystems. The API Mediation Layer is launched if GATEWAY is specified, and the Zowe desktop startup by DESKTOP . This allows you control which parts of Zowe you want to bring up for your end users. The GATEWAY is uses Apache Tomcat servers and requires Java to launch, the location of which is specified in the JAVA_HOME value. The DESKTOP is a node server which requires the NODE_HOME value to be set.

LAUNCH_COMPONENT_GROUPS=GATEWAY,DESKTOP

If you want to change any of the ports Zowe will use then edit these as well. Default static values for ports are provided in the instance.env when it is first created, and other values such as location of prerequisites are dynamically determined by the zowe-configure-instance.sh script that queries the z/OS environment. The full list of variables contained in instance.env is described in the documentation chapter Creating and configuring the Zowe instance directory.

Updating Zowe

If you have installed Zowe 1.9 and have created an instance directory, and then install Zowe 1.10, 1.14, … these will introduce a new Zowe runtime directory. You may re-use the same Zowe instance directory created and used with a previous version of Zowe, however it is recommended that you re-run zowe-configure-instance.sh from the newer runtimes with the -c argument pointing to the previously created instance directory. This updates the older instance directory with any new parameters introduced by the newer Zowe runtimes. If you are using an existing instance directoryinstance.env ensure that the ROOT_DIR value is updated to point to the correct <RUNTIME_DIR> directory.

ROOT_DIR=/u/winchj/zowe-1.9.0/runtime

Launching Zowe

Now that Zowe 1.9 has been installed and configured, the next step is to start it !

If you are starting the Zowe desktop then the cross memory server should be started. If its PROCLIB ZWESISTC has been installed correctly then you should issue the SDSF command /S ZWESISTC . The cross memory is a long running angel process and it should be started before the main Zowe started task. There is nothing user facing in the cross memory server, it is just used internally by the Zowe desktop to provide secure services.

The main Zowe started task (containing the API Mediation Layer and the Zowe desktop) can be launched either from SDSF or from USS. From USS execute the script <RUNTIME_DIR>/bin/zowe-start.sh .

Having run the zowe-start.sh script it echos to the console the name of the job ZWE1SV. If you want to control the job name his is done by updating the i key value pairs ZOWE_PREFIX=ZWE and ZOWE_INSTANCE=1 in the instance.env file. For example, on my system where I work alongside other Zowe developers I set ZOWE_PREFIX=ZWEJ , to distinguish the job apart from ZWEC or ZWES that they tend to use.

Check the progress of the ZWES1SV paying attention toSTDERR file for any errors. Common ones are the KEYSTORE_DIRECTORY in the instance.env file pointing to a directory that the user ID ZWESVUSR doesn’t have permission to read, or the user ID ZWESVUSR not having x permission on the parent directory path where the Zowe runtime and the Zowe instance directory. In a future blog I’ll cover more detail on the common Zowe startup errors that occur. The STDOUT will contain the ports that the Zowe instance is using.

In my instance.env file I specified GATEWAY_PORT=26502 which should be available as a URL to log onto https://<hostname>://26502.

To check the mediation layer works select the hyperlink The API Catalog is running at the top. This will take you to a logon page. If you are unable to log on it is likely that the connection to z/OSMF is failing. Check the values of the z/OSMF related parameters in the zowe-configure-certificates.env file used to generate the keystore directory. Try pinging z/OSMF also through its URL https://<hostname>:<port>/zosmf/info. If the log on to the Zowe API catalog is successful you will the available API services known to the API gateway.

The next step to verify that Zowe is up and running is to open the desktop. In my instance.env file I set ZOWE_ZLUX_SERVER_HTTPS_PORT=26508 . To open the desktop the URL is then https://<hostname>:26508 which should display the desktop login screen.

If you are unable to log onto the desktop this is likely to be a failure in the communication between the Zowe started task and the cross memory server, which can be diagnosed by looking at the ZIS status message written in the SYSOUTFor a list of possible problems and how to diagnose see the documentation Known Zowe Application Framework issues.

The screen shot above shows a successful log into the Zowe desktop, where I’ve started the TN3270 application, the File Editor to browse unix files, and the JES Explorer to show the JESMSGLG for the Zowe job itself !

If anyone runs into issues installing Zowe 1.9 please reach out to the squad members on the slack channel #zowe-install-rework. If you don’t have access to the slack workspace you can register your e-mail address at https://slack.openmainframeproject.org/.

If you enjoyed this blog checkout more Zowe blogs here. Or, join ask a question and join the conversation on the Open Mainframe Project Slack channel #Zowe-dev, #Zowe-user or #Zowe-onboarding.

Static Image for the article title