Installing Zowe via Zowe Server Install Wizard

The Zowe Server Install Wizard 1.0 is an installation wizard for Zowe server-side components available on Microsoft Windows, macOS, and Linux systems. Performing Zowe installation via the Wizard streamlines the installation process and is an alternative to performing manual Zowe server-side component installation. Review this article for details about installing Zowe server-side components via the Wizard, setting up the Wizard connection to z/OS, and details including sample JCLs for the Install Wizard initialization steps. There is also a troubleshooting section in case you encounter issues when installing Zowe via the Install Wizard.

note

The Zowe Server Install Wizard is currently available only as a technical preview. This preview includes some of the installation options. Future releases will include more options including validation and discovery properties that can assist with Zowe server installation.

This technical preview includes the following features:

• Install a PAX or SMP/E edition of Zowe (including offline PAX upload)
• Apply zwe init to perform configuration. JCL preview and z/OSMF Workflows support is currently not available in this technical preview.
• Use of certificates (PKCS12 or Keyring formats) generated by Zowe. The use of your organizations certificate without requiring manual edits to the zowe.yaml file is currently not supported.

Future Wizard releases will include post-install configuration tasks including customizing the behavior of individual Zowe components, and the enablement of tracing. Currently, these tasks must be performed manually in the zowe.yaml file.

tip

To review open issues, ask questions, find solutions, and report bugs, see Issues in the Zowe Server Install Wizard GitHub repository.

• Benefits of Wizard Installation
• Prerequisites of the Wizard
• Downloading the Wizard
• Installing Zowe server-side components
  • Connecting the Wizard to z/OS
  • Setting z/OSMF Attributes (optional)
• Choosing the Server Installation Type
• Configuring the Zowe Server
• Final Review
• Troubleshooting
  • Failure to establish a TLS connection
  • Unable to continue with Wizard installation

Benefits of Wizard installation

• Reduces the need for YAML editing in z/OS Unix by handling these operations for you based on inputs to the prompts presented in the Wizard UI.

• Inputs to the prompts are validated, so that invalid input or typos entered in most commands are prevented.

• The separation of duties for steps to be performed by a security administrator is made easier, whereby a system programmer or system administrator can skip particular steps where elevated user permissions are required, whereupon security administrators can perform such steps outside of the Wizard.

• Results for each step and the YAML configuration output can be reviewed for reference alongside activites performed outside of the Wizard, or for future use.

Prerequisites of the Wizard

• Zowe version 2.16.0 or above for SMP/E as well as .PAX
• Microsoft Windows, Apple macOS, or a Linux with an X11 or Wayland server display, which can install programs from .rpm or .deb formats
• An FTP or FTPS connection to z/OS for Zowe installation
• An account on z/OS that has access to z/OS UNIX for Zowe installation
• A security administrator to configure required permissions in z/OS and z/OSMF
• A security administrator to generate certificates for Zowe
• A network administrator to open ports used by Zowe

Downloading the Wizard

To download the latest version of the Wizard, visit Zowe.org. Ensure that you download the appropriate file extension type according to your operating system:

Operating System	File Extension Type
Microsoft Windows	.exe
Apple macOS	.dmg
Linux (debian-based)	.deb
Linux (RedHat or SuSE-based)	.rpm

Installing Zowe server-side components

Once the Wizard is installed, use the procedure as presented in the Wizard. The following steps outline the procedure and provide additional details.

1. On the landing page of the Zowe Server Installation Wizard, select from the two presented options:

• New Zowe Installation
  This option directs you to the Connection window. Provide details as presented in the following table: Connecting the Wizard to z/OS.
• Zowe Installation Dry Run
  This option allows you to follow the installation steps without running the installation.

Connecting the Wizard to z/OS

2. Set the following fields according to your environment:

Field name	Description
Host	Value for the target z/OS system for Zowe Installation. For example, mainframe.yourcompany.com
FTP Port	The FTP Port number for internal use. The default port is 21. If not specified, the Wizard uses the default port.
User Name	Your z/OS username.
Password	Your z/OS password.

3. Select Use FTP with TLS. This is the recommended option. Provide details as described in the following table:

Field name	Description
Min TLS	Select the minimum TLS version to accept the certificate from the server.
Max TLS	Select the maximum TLS version to accept the certificate from the server.

4. (Optional) You can select Accept all certificates. Note that selecting all certificiates disables certificate verification. Checking this option is not recommended.
5. Click VALIDATE CREDENTIALS.
6. Click Continue.
7. In the Before you start window, review the instructions. Customize the job statement, or use the default.
8. In the Job statement field, customize the job statement as necessary and click SAVE AND VALIDATE.
9. Further down the Planning page, provide details for z/OS Unix locations (including Node and Java), identifiers, and z/OSMF details.

Setting z/OSMF Attributes (optional)

Provide details for z/OSMF.

1. After specifying all the mandatory details, click VALIDATE LOCATIONS.

   You will receive a confirmation message for Java and Node.js locations.

2. Click Continue to Installation Options.

Choosing the Server Installation Type

1. In the Installation Type window, select one of the following three installation types in the Wizard:

   Download Zowe convenience build PAX from internet

   Download the latest Zowe convenience build in .PAX format from zowe.org using the Wizard without visiting the website.
   

   1. Click License Agreement.
      
   2. On the End User License Agreement for Zowe page, click AGREE.

   
   

   3. In Download Zowe Pax, click UNPAX and BEGIN DOWNLOAD. Ensure that all statuses finish before continuing to the next step.
   Upload Zowe PAX for offline install

   Use this option to upload a local (already downloaded) Zowe .PAX file.
   

   1. Click UPLOAD PAX.

   
   

   2. Select downloaded PAX file, and click Open.
   SMP/E

   Use this option to install Zowe through a SMP/E build outside the wizard.

   1. Provide the location of the Runtime Directory.

   2. Click VALIDATE LOCATION.
      Note: When using SMP/E installation, in the Initialization window, under the Installation tab, confirm the dataset names used during installation.

   3. Click Save.

2. Click Continue to Component Installation.

Configuring the Zowe Server

Perform Zowe server configuration in the Wizard by providing inputs to the prompts for configuration values. Some steps may require an administrator with sufficient privileges to complete the step.

The following actions can be performed during Wizard configuration:

• View/Edit Yaml
  This option lets you preview or adjust the YAML configuration that is used by Zowe. The prompts of the Wizard are used to automatically generate the YAML contents, but you also have the options to review, edit, or import and export contents of the YAML file. This option also allows you to copy the YAML in its current state, which can than be sent to an administrator that is authorized to perform the task. Copying the YAML also includes a relevant JCL sample and explanation for the particular step.

• View Job Output
  This option presents the results of the jobs that were submitted. Details are provided if a job fails or returns a warning. This option allows you to collect the job content which can be provide to an administrator without submitting it. Each value entered is validated against the schema.

• Skip
  This option makes it possible to skip an installation step that you cannot perform such as an administrative security action that you cannot perform yourself. This option makes it possible to complete an action external to the Wizard.

The following table presents the steps in the installation, detailed descriptions of the steps, and corresponding sample JCLs:

Install Wizard Initalization Step	Description	Sample JCL
Installation	Purpose: Create datasets for Zowe's PARMLIB content and non-ZFS extension content for a given Zowe Instance Action: 1. Allocate the PDSE FB80 dataset with at least 15 tracks named from Zowe parameter zowe.setup.dataset.parmlib 2. Allocate the PDSE FB80 dataset with at least 30 tracks named from Zowe parameter zowe.setup.dataset.authPluginLib 3. Copy the ZWESIP00 member from zowe.setup.dataset.prefix.SZWESAMP into zowe.setup.dataset.parmlib	ZWEIMVS
APF Auth	Purpose: Zowe contains one privileged component, ZIS, which enables the security model. The majority of Zowe is unprivileged and in key 8. The load library for the ZIS component and its extension library must be set as APF authorized and run in key 4. This enables ZIS and components that depend on ZIS. Action: 1. APF authorize the datasets defined at zowe.setup.dataset.authLoadlib and zowe.setup.dataset.authPluginLib. 2. Define PPT entries for the members ZWESIS01 and ZWESAUX as Key 4, NOSWAP in the SCHEDxx member of the system PARMLIB.	ZWEIAPF
Security	Purpose: The STC accounts for Zowe need permissions for operating servers, and users need permissions for interacting with the servers. Action: Set SAF permissions for accounts	RACF: ZWEIRAC TSS: ZWEITSS ACF2: ZWEIACF
Security	(z/OS v2.4 ONLY) Create Zowe SAF Resource Class	This is not needed on z/OS v2.5+. On z/OS v2.4, the SAF resource class for Zowe is not included, and must be created. See these samples for examples: RACF: ZWEIRACZ TSS: ZWEITSSZ ACF2: ZWEIACFZ
Certificates Option 1	Zowe creates a keyring and populates it with a newly generated certificate and certificate authority. The certificate would be seen as "self-signed" by clients unless import of the CA to clients is performed.	RACF: ZWEIKRR1 TSS: ZWEIKRT1 ACF2: ZWEIKRA1
Certificates Option 2	Zowe creates a keyring and populates the keyring by connecting pre-existing certificates and CAs that you specify.	RACF: ZWEIKRR2 TSS: ZWEIKRT2 ACF2: ZWEIKRA2
Certificates Option 3	Zowe creates a keyring and populates the keyring by importing PKCS12 content from a dataset that you specify.	RACF: ZWEIKRR3 TSS: ZWEIKRT3 ACF2: ZWEIKRA3
STC	Purpose: ZWESLSTC is the job for running Zowe's webservers. ZWESISTC runs the APF authorized cross-memory server. The ZWESASTC job is started by ZWESISTC on an as-needed basis. Action: Copy the members ZWESLSTC, ZWESISTC, and ZWESASTC into your desired PROCLIB. If the job names are customized, modify the job name YAML values in zowe.setup.security.stcs	ZWEISTC
(Optional) VSAM for Caching Service (NYI)	Purpose: To use VSAM as your storage method for the Caching Service. Note that Infinispan is the recommended storage method. For more information, see Using VSAM as a storage solution through the Caching service. Action: Create a RLM or NONRLM dataset for the Caching service, and set the name as the value for components.caching-service.storage.vsam.name	ZWECSVSM

Final Review

After completing the steps presented in the Wizard, a summary is provided indicating which steps were completed, skipped, or have errors. Errors are stored and can be reviewed in View Job Output. You can revisit any step to retry performing the step. You also have the option to export the final generated YAML file.

Troubleshooting

Failure to establish a TLS connection

When attempting to establish a TLS connection, you may encounter the following message:

Client network socket disconnected before secure TLS connection was established

If you receive this message, go back to the Connection page and attempt to re-establish the connection. If the connection cannot be established, restart the Wizard.

Unable to continue with Wizard installation

If you encounter strange behavior that prohibits you from continuing with Wizard installation, we recommend you follow this procedure:

1. View the Job output within the Wizard.

2. If the error is not clear from the Job output, view the output of the log file according to your platform:

   For Windows

   %USERPROFILE%\AppData\Roaming{app name}\logs\main.log

   For macOS

   ~/Library/Logs/{app name}/main.log

   For Linux

   ~/.config/{app name}/logs/main.log

If you are still unsure how to proceed, you can optionally make a backup of these log files, and then use the following procedure to remove the Wizard's cache.

1. Close the Wizard.

2. Follow the steps according to your operating system:

   For Windows

   1. Open File Explorer. In the address bar type %APPDATA%. This takes you to the directory where your app data is stored. The typical directory path is C:\Users[Your User Name]\AppData\Roaming.

   2. Locate the folder corresponding to zowe-install-wizard.

   For macOS

   1. Open Finder. In the menu bar select Go > Go to Folder.

   2. Type ~/Library/Application Support/ and press Enter.

   3. Locate the folder corresponding to zowe-install-wizard

   For Linux

   1. Open a terminal or file manager.

   2. Navigate to ~/.config/, which is where most apps store their configuration data.

   3. In the terminal, enter the following command: cd ~/.config/.

   4. Locate the folder corresponding to zowe-install-wizard.

3. Delete this folder to remove all stored data.

4. Restart the Wizard.

Unable to save setting to zowe.yaml via the Wizard's UI or editor

The accurate updating & saving to YAML in the UI may not always work as intended. If you have issues saving a specific setting to the Zowe configuration YAML via the Wizard's UI or editor (or an advanced setting is not available to be edited), it is recommended to make a manual edit to the configuration YAML file in z/OS Unix & then proceed with the Wizard as intended.