Installing Zowe on z/OS

Last Updated: 1/25/2019, 3:28:47 PM

Installing Zowe on z/OS

To install Zowe on z/OS, you install the Zowe runtime that consists of three components: Zowe Application Framework, explorer server, and Zowe API Mediation Layer. Follow the instructions in this topic to obtain the installation file for z/OS runtime components and run the installation scripts.

  1. Obtaining and preparing the installation file
  2. Prerequisites
  3. Installing the Zowe runtime on z/OS
  4. Starting and stopping the Zowe runtime on z/OS
  5. Verifying installation
  6. Looking for troubleshooting help?

Obtaining and preparing the installation file

The Zowe installation file for Zowe z/OS components are distributed as a PAX file that contains the runtimes and the scripts to install and launch the z/OS runtime. For each release, there is a PAX file named zowe-v.r.m.pax, where

  • v indicates the version
  • r indicates the release number
  • m indicates the modification number

The numbers are incremented each time a release is created so the higher the numbers, the later the release.

To download the PAX file, open your web browser and click the DOWNLOAD Zowe z/OS Components button on the Zowe Download website to save it to a folder on your desktop. After you obtain the PAX file, follow the procedures below to verify the PAX file and prepare it to install the Zowe runtime.

Follow these steps:

  1. Verify the integrity of the PAX file to ensure that the file you download is officially distributed by the Zowe project.


    • The commands in the following steps are tested on both Mac OS X V10.13.6 and Ubuntu V16.04 and V17.10.
    • Ensure that you have GPG installed. Click here to download and install GPG.
    • The v.r.m in the commands of this step is a variable. You must replace it with the actual PAX file version, for example, 0.9.0.

    Step 1: Verify the hash code.

    Download the hash code file zowe-v.r.m.pax.sha512 from the Zowe website. Then, run the following commands to check:

    (gpg --print-md SHA512 zowe-v.r.m.pax > && diff zowe-v.r.m.pax.sha512 && echo matched || echo "not match"

    When you see "matched", it means the PAX file that you download is the same one that is officially distributed by the Zowe project. You can delete the temporary "" file.

    You can also use other commands such as sha512, sha512sum, or openssl dgst -sha512 to generate SHA512 hash code. These hash code results are in a different format from what Zowe provides but the values are the same.

    Step 2. Verify with signature file.

    In addition to the SHA512 hash, the hash is also verifiable. This is done by digitally signing the hash text file with a KEY from one of the Zowe developers.

    Follow these steps:

    1. Download the signature file zowe-v.r.m.pax.asc from Zowe website, and download the public key KEYS from
    2. Import the public key with command gpg --import KEYS.
    3. If you have never used gpg before, generate keys with command gpg --gen-key.
    4. Sign the downloaded public key with command gpg --sign-key DC8633F77D1253C3.
    5. Verify the file with command gpg --verify zowe-v.r.m.pax.asc zowe-v.r.m.pax.
    6. Optional: You can remove the imported key with command: gpg --delete-key DC8633F77D1253C3.

    When you see output similar to the followin one, it means the PAX file that you download is the same one that is officially distributed by the Zowe project.

    gpg: Signature made Tue 14 Aug 2018 08:29:46 AM EDT
    gpg: using RSA key DC8633F77D1253C3
    gpg: Good signature from "Matt Hogstrom (CODE SIGNING KEY) " [full]
  2. Transfer the PAX file to z/OS.

    Follow these steps:

    a. 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.

    b. Connect to z/OS using SFTP. Issue the following command:

    sftp <>

    If SFTP is not available or if you prefer to use FTP, you can issue the following command instead:

    ftp <>

    Note: When you use FTP, switch to binary file transfer mode by issuing the following command:


    c. Navigate to the target directory that you wish to transfer the Zowe PAX file into on z/OS.

    Note: After you connect to z/OS and enter your password, you enter into 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.

    d. When you are in the directory you want to transfer the Zowe PAX file into, issue the following command:

    put <pax-file-name>.pax

    Where pax-file-name is a variable that indicates the full 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 will list contents of a directory on z/OS.

  3. When the PAX file is transferred, expand the PAX file by issuing the following command in an ssh session:

    pax -ppx -rf <pax-file-name>.pax

    Where pax-file-name is a variable that indicates the name of the PAX file you downloaded.

    This will expand to a file structure.


    Note: The PAX file will expand into the current directory. A good practice is to keep the installation directory apart from the directory that contains the PAX file. To do this, you can create a directory such as /zowe/paxes that contains the PAX files, and another such as /zowe/builds. Use SFTP to transfer the Zowe PAX file into the /zowe/paxes directory, use the cd command to switch into /zowe/builds and issue the command pax -ppx -rf ../paxes/<zowe-v.r.m>.pax. The /install folder will be created inside the zowe/builds directory from where the installation can be launched.


  • Before you start the installation on z/OS, ensure that your environment meets the necessary prerequisites that are described in System requirements.

    You can run a script to check the install condition of the required prerequisites. To do this, issue the following command with the current directory being the /install directory.

    The script writes messages to your terminal window. The results are marked OK, Info, Warning or Error. Correct any reported errors and rerun the command to ensure that no errors exist before you run the script to install the Zowe runtime. The script does not change any settings. You can run it as often as required before you install the Zowe runtime.

  • The user ID that is used to perform the installation must have authority to set the '-a' extattr flag. This requires a minimum of read access to the BPX.FILEATTR.APF resource profile in the RACF CLASS if you use RACF. It is not essential for this access to be enabled before you run the script that installs Zowe runtime on z/OS. However, this access must be enabled before you run the script.

Installing the Zowe runtime on z/OS

To install Zowe API Mediation Layer, Zowe Application Framework, and explorer server, you install the Zowe runtime on z/OS.

Follow these steps:

  1. Navigate to the directory where the installation archive is extracted. Locate the /install directory.

  2. Review the zowe-install.yaml file which contains the following properties:

    • install:rootDir is the directory that Zowe installs to create a Zowe runtime. The default directory is ~/zowe/0.9.5. The user's home directory is the default value. This ensures that the user who performs the installation has permission to create the directories that are required for the installation. If the Zowe runtime will be maintained by multiple users, it is recommended to use another directory, such as /var/zowe/v.r.m.

      You can run the installation process multiple times with different values in the zowe-install.yaml file to create separate installations of the Zowe runtime. Ensure that the directory where Zowe will be installed is empty. The install script exits if the directory is not empty and creates the directory if it does not exist.

    • Zowe API Mediation Layer has three HTTPS ports, one for each micro-service.

    • The Explorer-server has two ports: one for HTTP and one for HTTPS. The liberty server is used for the explorer-ui components.

    • The zlux-server has three ports: the HTTP and HTTPS ports that are used by the Zowe Application Server, and the port that is used by the ZSS Server.


    # http and https ports for the node server


    • If all of the default port values are acceptable, the ports do not need to be changed. To allocate ports, ensure that the ports are not in use for the Zowe runtime servers.
    • Comments are not supported in the yaml file, apart from lines starting with '#' in column one.
  3. Determine which ports are not available.

    a. Display a list of ports that are in use with the following command:


    b. Display a list of reserved ports with the following command:


    The zowe-install.yaml also contains the telnet and SSH port with defaults of 23 and 22. If your z/OS LPAR is using different ports, edit the values. This allows the TN3270 terminal desktop application to connect as well as the VT terminal desktop application.

    Note: Unlike the ports needed by the Zowe runtime for its Zowe Application Framework and explorer server which must be unused, the terminal ports are expected to be in use.

    # Ports for the TN3270 and the VT terminal to connect to
  4. Select the ZOWESVR PROCLIB member.

    The zowe-install.yaml file contains the dataset name and member name of the ZOWESVR JCL to be used to run Zowe.


    # started task JCL member for Zowe job
    # dsName=SYS1.PROCLIB   

    Follow these steps:

    a. Specify the dataset name of the PROCLIB member you want to use with the dsName tag. For example,


    The following guidelines apply.

    • Do not enclose the dataset name in quotes.
    • The dataset name is not case-sensitive, but the dsName tag is case-sensitive and must be written exactly as shown.
    • The dataset name must be an existing z/OS dataset in the PROCLIB concatenation. The user installing Zowe must have update access to this dataset.
    • If you omit the dsName tag or specify dsName=auto, the install script scans the available PROCLIB datasets and places the JCL member in the first dataset where the installing user has write access. For further details, see How the install script works.

    b. Specify the member name of the PROCLIB member you want to use with the memberName tag. For example,


    The following guidelines apply.

    • Do not enclose the member name in quotes.
    • The member name is not case-sensitive, but the memberName tag is case-sensitive and must be written exactly as shown.
    • The member name must be a valid PDS member name in z/OS. If the member already exists, it will be overwritten.
    • If you omit the memberName tag or specify memberName=, the install script uses ZOWESVR.
  5. (Optional) Use existing certificate signed by an external CA for HTTPS ports in API Mediation Layer and zLUX.

    If you skip this step, then certificates generated by the local API Mediation CA are used. These certificates are generated automatically during the installation. The server certificate needs to be imported to your browser - see Import the local CA certificate to your browser.

    You can use an existing server certificate that is signed by an external CA such as a CA managed by the IT department of your company. The benefit of such certificate is that it will be trusted by browsers in your company. You can even use a public certificate authority such as Symantec, Comodo, or GoDaddy. Such certificate are trusted by all browsers and most REST API clients. This is, however, a manual process of requesting a certificate. As such, we recommend to start with the local API Mediation Layer CA for an initial evaluation.

    You can use an existing certificate with the following procedure.

    Follow these steps:

    a. Update the value of externalCertificate in the api-mediation section of the YAML file. The value needs to point to a keystore in PKCS12 format that contains the certificate with its private key. The file needs to be transferred as a binary to the z/OS system. Currently only the PKCS12 keystore with the password set to password are supported.

    b. Update the value of externalCertificateAlias to the alias of the server certificate in the keystore.

    c. Update the value of externalCertificateAuthorities to the path of the public certificate of the certificate authority that has the signed the certificate. You can add additional certificate authorities separated by spaces. This can be used for certificate authorities that have signed the certificates of the services that you want to access via the API Mediation Layer.

    d. (Optional) If you have trouble getting the certificates and you want only to evaluate Zowe, you can switch off the certificate validation by setting verifyCertificatesOfServices=false. The HTTPS will still be used but the API Mediation Layer will not validate any certificate.

    Important Switching off certificate evaluation is a non-secure setup.


  6. Execute the script.

    With the current directory being the /install directory, execute the script by issuing the following command:  

    Note: You might receive the following error that the file cannot be executed: cannot execute

    The error occurs when the install script does not have execute permission. To add execute permission, issue the following command:

    chmod u+x

    You may also receive the following error: --action trust-zosmf has failed.
    WARNING: z/OSMF is not trusted by the API Mediation Layer. Follow instructions in Zowe documentation about manual steps to trust z/OSMF

    This error does not interfere with installation progress and can be remediated after the install completes. See Trust z/OSMF Certificate for more details.

  7. Configure Zowe as a started task.

    The ZOWESVR must be configured as a started task (STC) under the IZUSVR user ID.

    • If you use RACF, issue the following commands:

    • If you use CA ACF2, issue the following commands:

    • If you use CA Top Secret, issue the following commands:

  8. Add the users to the required groups, IZUADMIN for administrators, and IZUUSER for standard users.

    • If you use RACF, issue the following command:

    • If you use CA ACF2, issue the following commands:

      ACFNRULE TYPE(TGR) KEY(IZUADMIN) ADD(UID(<uid string of user>) ALLOW)
    • If you use CA Top Secret, issue the following commands:

      TSS ADD(userid)  GROUP(IZUADMGP)

How the install script works

When the script runs, it performs a number of steps broken down into the following sections. Review the sections to help you undertand messsages and issues that might occur when you run the script and actions you can take to resolve the issues.

  1. Environment variables

    To prepare the environment for the Zowe runtime, a number of ZFS folders need to be located for prerequisites on the platform that Zowe needs to operate. These can be set as environment variables before the script is run. If the environment variables are not set, the install script will attempt to locate default values.

    • ZOWE_ZOSMF_PATH: The path where z/OSMF is installed. Defaults to /usr/lpp/zosmf/lib/defaults/servers/zosmfServer
    • ZOWE_JAVA_HOME: The path where 64 bit Java 8 or later is installed. Defaults to /usr/lpp/java/J8.0_64
    • ZOWE_EXPLORER_HOST: The hostname of where the explorer servers are launched from. Defaults to running hostname -c

    When you run the install script for the first time, the script attempts to locate environment variables. The install script creates a files named .zowe_profile that resides in the current user's home directory and adds lines that specify the values of the environment variables to the file. The next time you run the install script, it uses the same values in this file.

    Each time you run the install script, it retrieves environment variable settings in the following ways.

    • When the .zowe-profile file exists in the home diretory, the install script uses the values in this file to set the environment variables.
    • When the .zowe-profile file does not exist, the install script checks if the .profile file exists in the home directory. If it does exist, the install script uses the values in this file to set the environment variables.

    You can create, edit, or delete the .zowe_profile file (as needed) before each install to set the variables to the values that you want. We recommend that you do not add commands to the .zowe_profile file, with the exception of the export command and shell variable assignments.

    Note: If you wish to set the environment variables for all users, add the lines to assign the variables and their values to the file /etc/.profile.

    If the environment variables for ZOWE_ZOSMF_PATH, ZOWE_JAVA_HOME are not set and the install script cannot determine a default location, the install script will prompt for their location. The install script will not continue unless valid locations are provided.

  2. Expanding the PAX files

    The install script will create the Zowe runtime directory structure using the install:rootDir value in the zowe-install.yaml file. The runtime components of the Zowe server are then unpaxed into the directory that contains a number of directories and files that make up the Zowe runtime.

    If the expand of the PAX files is successful, the install script will report that it ran its install step to completion.

  3. Changing Unix permissions

    After the install script lays down the contents of the Zowe runtime into the rootDir, the next step is to set the file and directory permissions correctly to allow the Zowe runtime servers to start and operate successfully.

    The install process will execute the file scripts/ in the Zowe runtime directory. If the script is successful, the result is reported. If for any reason the script fails to run because of insufficient authority by the user running the install, the install process reports the errors. A user with sufficient authority should then run the If you attempt to start the Zowe runtime servers without the having successfully completed, the results are unpredictable and Zowe runtime startup or runtime errors will occur.

  4. Creating the PROCLIB member to run the Zowe runtime

    Note: The name of the PROCLIB member might vary depending on the standards in place at each z/OS site, however for this documentation, the PROCLIB member is called ZOWESVR.

    At the end of the installation, a Unix file ZOWESVR.jcl is created under the directory where the runtime is installed into, $INSTALL_DIR/files/templates. The contents of this file need to be tailored and placed in a JCL member of the PROCLIB concatenation for the Zowe runtime to be executed as a started task. The install script does this automatically. If the user specifies dsName=auto, or omits the dsName tag, or sets it to null by coding dsName=, the install script proceeds as follows and stops after the first successful write to the destination PROCLIB.

    1. Try JES2 PROCLIB concatenation.
    2. Try master JES2 JCL.
    3. Try SYS1.PROCLIB.

    If this succeeds, you will see a message like the following one:


    Otherwise you will see messages beginning with the following information:

    Failed to put ZOWESVR.JCL in a PROCLIB dataset.

    In this case, you need to copy the PROC manually. Issue the TSO oget command to copy the ZOWESVR.jcl file to the preferred PROCLIB:

    oget '$INSTALL_DIR/files/templates/ZOWESVR.jcl' 'MY.USER.PROCLIB(ZOWESVR)'

    You can place the PROC in any PROCLIB data set in the PROCLIB concatenation, but some data sets such as SYS1.PROCLIB might be restricted, depending on the permission of the user.

    You can tailor the JCL at this line

    //ZOWESVR   PROC SRVRPATH='/zowe/install/path/explorer-server'

    to replace the /zowe/install/path with the location of the Zowe runtime directory that contains the explorer server. Otherwise you must specify that path on the START command when you start Zowe in SDSF:

    /S ZOWESVR,SRVRPATH='$ZOWE_ROOT_DIR/explorer-server'

Starting and stopping the Zowe runtime on z/OS

Zowe has three runtime components on z/OS: the explorer server, the Zowe Application Server, and Zowe API Mediation Layer. When you run the ZOWESVR PROC, all of these components start. The Zowe Application Server startup script also starts the zSS server, so starting the ZOWESVR PROC starts all the four servers. Stopping ZOWESVR PROC stops all four servers.

Starting the ZOWESVR PROC

To start the ZOWESVR PROC, run the script at the Unix Systems Services command prompt:

cd $ZOWE_ROOT_DIR/scripts


$ZOWE_ROOT_DIR is the directory where you installed the Zowe runtime. This script starts the ZOWESVR PROC for you so you do not have to log on to TSO and use SDSF.

Note: The default startup allows self-signed and expired certificates from the Zowe Application Framework proxy data services such as the explorer server.

If you prefer to use SDSF to start Zowe, start ZOWESVR by issuing the following operator command in SDSF:


By default, Zowe uses the runtime version that you most recently installed. To start a different runtime, specify its server path on the START command:


To test whether the explorer server is active, open the URL: https://<hostname>:7443/explorer-mvs.

The port number 7443 is the default port. You can overwrite this port in the zowe-install.yaml file before the script is run. See Step 2 in [Installing Zowe runtime on z/OS](# #installing-the-zowe-runtime-on-z-os).

Stopping the ZOWESVR PROC

To stop the ZOWESVR PROC, run the script at the Unix Systems Services command prompt:

cd $ZOWE_ROOT_DIR/scripts

If you prefer to use SDSF to stop Zowe, stop ZOWESVR by issuing the following operator command in SDSF:


Either method will stop the explorer server, the Zowe Application Server, and the zSS server.

When you stop the ZOWESVR, you might get the following error message:


This error results when there is more than one started task named ZOWESVR. To resolve the issue, stop the required ZOWESVR instance by issuing the following commands:


You can obtain the asid from the value of A=asid when you issue the following commands:


Verifying installation

Once Zowe is running and the startup sequence is complete, you can check the configuration files and jobs for Zowe on your z/OS system to ensure that the installation process is successful. To do this, follow these steps.

  1. Navigate to the runtime $ZOWE_ROOT_DIR/scripts directory, where $ZOWE_ROOT_DIR is the location of the Zowe runtime directory that contains the explorer server.

  2. Run the script by issuing the following command:

The script writes its messages to your terminal window. The results are marked OK, Info, Warning or Error. Correct any reported errors and restart the Zowe server. The script does not change any settings, so you can run it as often as required.

Next steps

Follow the instructions in the following sections to verify that the components are installed correctly and are functional.

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/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html


  • myHost is the host on which you installed the Zowe Application Server.
  • httpPort is the port number that is assigned to node.http.port in zluxserver.json.
  • httpsPort is the port number that is assigned to node.https.port in zluxserver.json. For example, if the Zowe Application Server runs on host myhost and the port number that is assigned to node.http.port is 12345, you specify https://myhost:12345/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.htm.

Verifying explorer server installation

After the explorer server is installed and the ZOWESVR procedure is started, you can verify the installation from an internet browser by entering the following case-sensitive URL:



  • your.server is the host name or IP address of the z/OS® system where explorer server is installed
  • atlasport is the port number that is chosen during installation. You can verify the port number in the server.xml file. This file is located in the explorer server installation directory, which is /var/zowe/explorer-server/wlp/usr/servers/Atlas/server.xml by default. The port number is visible in the httpsPort assignment in the server.xml file.

Example: httpPort="7443".

This URL sends an HTTP GET request to the Liberty Profile explorer server. If explorer server is installed correctly, a JSON payload that indicates the current explorer server application version is returned.


{ "version": "V0.0.1" }

Note: The first time that you interact with the explorer server, you are prompted to enter an MVS™ user ID and password. The MVS user ID and password are passed over the secure HTTPS connection to establish authentication.

After you verify that explorer server is successfully installed, you can access the UI at the following URLs:

  • https://<your.server>:<atlasport>/ui/v1/jobs/#/
  • https://<your.server>:<atlasport>/ui/v1/datasets/#/
  • https://<your.server>:<atlasport>/ui/v1/uss/#/

If explorer server is not installed successfully, see Troubleshooting installation for solutions.

Verifying the availability of explorer server REST APIs

To verify the availability of all explorer server REST APIs, use the Liberty Profile's REST API discovery feature from an internet browser with the following URL. This URL is case-sensitive.


With the discovery feature, you can also try each discovered API. The users who verify the availability must have access to their data sets and job information by using relevant explorer server APIs. This ensures that your z/OSMF configuration is valid, complete, and compatible with the explorer server application. For example, try the following APIs:

Explorer server: JES Jobs APIs

GET /api/v1/jobs

This API returns job information for the calling user.

Explorer server: Data set APIs

GET /api/v1/datasets/userid.**

This API returns a list of the userid.** MVS data sets.

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:


The hostName is set during install, and basePort is set as the gatewayHttpsPort parameter.


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

$ curl -v -k --silent https://hostName:basePort/api/v1/apicatalog/application/state 2>&1 | grep -Po '(?<=\"status\"\:\")[^\"]+'

The response UP confirms that API Mediation Layer is installed and is running properly.

Looking for troubleshooting help?

If you encounter unexpected behavior when installing or verifying Zowe runtime, see the Troubleshooting section for troubleshooting tips.