-
Notifications
You must be signed in to change notification settings - Fork 133
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
renamed existing zen doc version and added new doc version 1.0.1 (#3867)
* renamed existing zen doc version and added new doc version Signed-off-by: lparadkar-rocket <lparadkar@rocketsoftware.com> * added sidebar items and updated wizard doc Signed-off-by: lparadkar-rocket <lparadkar@rocketsoftware.com> * added version number in the first para of the doc Signed-off-by: lparadkar-rocket <lparadkar@rocketsoftware.com> * updated the error message Signed-off-by: lparadkar-rocket <lparadkar@rocketsoftware.com> * fix sidebar fers Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com> * fix sidebars for 2.18 and 2.17 Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com> * fix sidebar refs Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com> * language refactor of note Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com> * fix anchor link Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com> * added note for version 1.0.1 Signed-off-by: lparadkar-rocket <lparadkar@rocketsoftware.com> --------- Signed-off-by: lparadkar-rocket <lparadkar@rocketsoftware.com> Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com> Co-authored-by: Andrew Jandacek <andrew.jandacek@broadcom.com>
- Loading branch information
1 parent
6306bd9
commit b5997d5
Showing
2 changed files
with
280 additions
and
6 deletions.
There are no files selected for viewing
266 changes: 266 additions & 0 deletions
266
docs/user-guide/install-zowe-server-install-wizard-1-0-0.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,266 @@ | ||
| # 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](https://github.com/zowe/zen/issues) in the Zowe Server Install Wizard GitHub repository. | ||
| ::: | ||
|
|
||
| * [Benefits of Wizard Installation](#benefits-of-wizard-installation) | ||
| * [Prerequisites of the Wizard](#prerequisites-of-the-wizard) | ||
| * [Downloading the Wizard](#downloading-the-wizard) | ||
| * [Installing Zowe server-side components](#installing-zowe-server-side-components) | ||
| * [Connecting the Wizard to z/OS](#connecting-the-wizard-to-zos) | ||
| * [Setting z/OSMF Attributes (optional)](#setting-zosmf-attributes-optional) | ||
| * [Choosing the Server Installation Type](#choosing-the-server-installation-type) | ||
| * [Configuring the Zowe Server](#configuring-the-zowe-server) | ||
| * [Final Review](#final-review) | ||
| * [Troubleshooting](#troubleshooting) | ||
| * [Failure to establish a TLS connection](#failure-to-establish-a-tls-connection) | ||
| * [Unable to continue with Wizard installation](#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](https://www.zowe.org/download.html). | ||
| 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: | ||
|
|
||
| <details> | ||
| <summary>Download Zowe convenience build PAX from internet</summary> | ||
|
|
||
| Download the latest Zowe convenience build in .PAX format from [zowe.org](https://zowe.org) using the Wizard without visiting the website. <br /> | ||
| 1. Click **License Agreement**. <br /> | ||
| 2. On the _End User License Agreement for Zowe_ page, click **AGREE**. | ||
| <br /> | ||
| 3. In Download Zowe Pax, click **UNPAX** and **BEGIN DOWNLOAD**. Ensure that all statuses finish before continuing to the next step. | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Upload Zowe PAX for offline install</summary> | ||
|
|
||
| Use this option to upload a local (already downloaded) Zowe .PAX file. <br /> | ||
|
|
||
| 1. Click **UPLOAD PAX**. | ||
| <br /> | ||
| 2. Select **downloaded PAX file**, and click **Open**. | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>SMP/E</summary> | ||
|
|
||
| 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. | ||
|
|
||
| 2. Click **Save**. | ||
| </details> | ||
|
|
||
| 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:**<br /> Create datasets for Zowe's PARMLIB content and non-ZFS extension content for a given Zowe Instance<br /><br />**Action:**<br />1. Allocate the PDSE FB80 dataset with at least 15 tracks named from Zowe parameter `zowe.setup.dataset.parmlib`<br />2. Allocate the PDSE FB80 dataset with at least 30 tracks named from Zowe parameter `zowe.setup.dataset.authPluginLib`<br />3. Copy the ZWESIP00 member from `zowe.setup.dataset.prefix`.SZWESAMP into `zowe.setup.dataset.parmlib`|[ZWEIMVS](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEIMVS)| | ||
| |APF Auth|**Purpose:**<br /> 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.<br /><br />**Action:**<br />1. APF authorize the datasets defined at `zowe.setup.dataset.authLoadlib` and `zowe.setup.dataset.authPluginLib`.<br />2. <!-- This should be validated --> Define PPT entries for the members ZWESIS01 and ZWESAUX as Key 4, NOSWAP in the SCHEDxx member of the system PARMLIB.|[ZWEIAPF](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEIAPF)| | ||
| |Security|**Purpose:**<br /> The STC accounts for Zowe need permissions for operating servers, and users need permissions for interacting with the servers.<br /><br />**Action:**<br /> [Set SAF permissions for accounts](https://docs.zowe.org/stable/user-guide/assign-security-permissions-to-users#security-permissions-reference-table)|RACF: [ZWEIRAC](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEIRAC)<br /><br />TSS: [ZWEITSS](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEITSS)<br /><br />ACF2: [ZWEIACF](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/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:<br /><br />RACF: [ZWEIRACZ](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEIRACZ)<br /><br />TSS: [ZWEITSSZ](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEITSSZ)<br /><br />ACF2: [ZWEIACFZ](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/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](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEIKRR1)<br /><br />TSS: [ZWEIKRT1](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEIKRT1)<br /><br />ACF2: [ZWEIKRA1](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEIKRA1)| | ||
| |Certificates Option 2|Zowe creates a keyring and populates the keyring by connecting pre-existing certificates and CAs that you specify.|RACF: [ZWEIKRR2](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEIKRR2)<br /><br />TSS: [ZWEIKRT2](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEIKRT2)<br /><br />ACF2: [ZWEIKRA2](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEIKRA2)| | ||
| |Certificates Option 3|Zowe creates a keyring and populates the keyring by importing PKCS12 content from a dataset that you specify.|RACF: [ZWEIKRR3](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEIKRR3)<br /><br />TSS: [ZWEIKRT3](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEIKRT3)<br /><br />ACF2: [ZWEIKRA3](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEIKRA3)| | ||
| |STC|**Purpose**:<br /> 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.<br /><br />**Action**:<br /> 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](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/ZWEISTC)| | ||
| |(Optional) VSAM for Caching Service (NYI)|**Purpose:**<br /> 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](../extend/extend-apiml/api-mediation-vsam.md).<br /><br />**Action:**<br /> 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](https://github.com/zowe/zowe-install-packaging/tree/feature/v3/jcl/files/SZWESAMP/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: | ||
|
|
||
| <details> | ||
| <summary>For Windows</summary> | ||
|
|
||
| `%USERPROFILE%\AppData\Roaming{app name}\logs\main.log` | ||
| </details> | ||
|
|
||
| <details> | ||
| <summary>For macOS</summary> | ||
|
|
||
| ` ~/Library/Logs/{app name}/main.log` | ||
| </details> | ||
|
|
||
| <details> | ||
| <summary>For Linux</summary> | ||
|
|
||
| ` ~/.config/{app name}/logs/main.log` | ||
| </details> | ||
|
|
||
| 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: | ||
| <details> | ||
| <summary>For Windows</summary> | ||
|
|
||
| 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`. | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>For macOS</summary> | ||
|
|
||
| 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` | ||
| </details> | ||
|
|
||
| <details> | ||
| <summary>For Linux</summary> | ||
|
|
||
| 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`. | ||
| </details> | ||
|
|
||
| 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. |
Oops, something went wrong.