diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 97a4467676..e2163d98cd 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -1,6 +1,6 @@ // load versions list const ZOWE_VERSIONS = require('./versions.json') -const CURRENT_ZOWE_VERSION = '1.21.0 LTS' +const CURRENT_ZOWE_VERSION = '1.22.0 LTS' // Due to VuePress limitation, publish url path cannot have dot (.) inside // so we convert it to dash const PUBLISH_TARGET_PATH = (process.env.PUBLISH_TARGET_PATH || 'stable').replace(/\./g, '-') @@ -131,7 +131,7 @@ module.exports = { version: CURRENT_ZOWE_VERSION, base: `/${PUBLISH_TARGET_PATH}/`, dest: `.deploy/${PUBLISH_TARGET_PATH}/`, - description: 'Version 1.21.x LTS', + description: 'Version 1.22.x LTS', extraWatchFiles: [ '.vuepress/theme/' ], diff --git a/docs/.vuepress/pages.json b/docs/.vuepress/pages.json index b28263b68a..8af1e3fc29 100644 --- a/docs/.vuepress/pages.json +++ b/docs/.vuepress/pages.json @@ -42,10 +42,10 @@ "baseuri": "/user-guide/", "items": [ { - "text": "Planning and preparing the installation", + "text": "Planning and preparing the z/OS installation", "items": [ "user-guide/installandconfig.md", - "user-guide/systemrequirements.md", + "user-guide/systemrequirements-zos.md", "user-guide/install-nodejs-zos.md", "user-guide/systemrequirements-zosmf.md", "user-guide/systemrequirements-zosmf-lite.md", @@ -83,9 +83,20 @@ "user-guide/configuring-docker.md" ] }, + { + "text": "Zowe High Availability", + "items": [ + "user-guide/install-ha-sysplex.md", + "user-guide/configure-sysplex.md", + "user-guide/systemrequirements-zosmf-ha.md", + "user-guide/configure-caching-service-ha.md", + "user-guide/configure-zowe-ha-server.md" + ] + }, { "text": "Installing Zowe CLI", "items": [ + "user-guide/systemrequirements-cli.md", "user-guide/cli-installcli.md", "user-guide/install-cli-via-proxy.md", "user-guide/cli-updatingcli.md", diff --git a/docs/.vuepress/public/Zowe_Documentation_1.21.0.pdf b/docs/.vuepress/public/Zowe_Documentation_1.21.0.pdf new file mode 100644 index 0000000000..aea10b365d Binary files /dev/null and b/docs/.vuepress/public/Zowe_Documentation_1.21.0.pdf differ diff --git a/docs/.vuepress/versions.json b/docs/.vuepress/versions.json index 1522695511..30518b05a4 100644 --- a/docs/.vuepress/versions.json +++ b/docs/.vuepress/versions.json @@ -1,7 +1,11 @@ [{ - "text": "v1.21.x LTS", + "text": "v1.22.x LTS", "link": "stable/" }, +{ + "text": "v1.21.x LTS", + "link": "v1-21-x/" +}, { "text": "v1.20.x LTS", "link": "v1-20-x/" diff --git a/docs/README.md b/docs/README.md index db2a7a4d10..d92a0086fa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -105,9 +105,10 @@ footer: Except where otherwise noted, content on this site is licensed under a C ### Zowe documentation -You can download the Version 1.x.x Zowe documentation in PDF format from the links below. The latest version on this website is 1.21.0. +You can download the Version 1.x.x Zowe documentation in PDF format from the links below. The latest version on this website is 1.22.0. -**[V1.21.x](https://docs.zowe.org/stable/Zowe_Documentation.pdf)** | +**[V1.22.x](https://docs.zowe.org/stable/Zowe_Documentation.pdf)** | +**[V1.21.x](./Zowe_Documentation_1.21.0.pdf)** | **[V1.20.x](./Zowe_Documentation_1.20.x.pdf)** | **[V1.19.x](./Zowe_Documentation_1.19.1.pdf)** | **[V1.18.0](./Zowe_Documentation_1.18.0.pdf)** | diff --git a/docs/extend/extend-apiml/service-information.md b/docs/extend/extend-apiml/service-information.md index d4dc8a4099..c1b3e9ada2 100644 --- a/docs/extend/extend-apiml/service-information.md +++ b/docs/extend/extend-apiml/service-information.md @@ -50,6 +50,8 @@ RECKEY APIML ADD(SERVICES SERVICE(READ) ROLE(user) ALLOW) F ACF2,REBUILD(ZWE) ``` +API Gateway can be configured to check for SAF resource authorization in several ways. For details, see [SAF Resource Checking](../../user-guide/api-mediation/api-gateway-configuration.md#saf-resource-checking) + ## API Endpoints ### Obtain Information about a Specific Service diff --git a/docs/extend/install-configure-zos-extensions.md b/docs/extend/install-configure-zos-extensions.md index 7252568d26..5c302f6d12 100644 --- a/docs/extend/install-configure-zos-extensions.md +++ b/docs/extend/install-configure-zos-extensions.md @@ -1,40 +1,74 @@ -# Install and configure Zowe server component +# Install, upgrade, and configure Zowe server component -Learn how to install and configure the Zowe server components or extensions manually or by using scripts `zowe-install-component.sh` and `zowe-configure-component.sh`. +Learn how to install, upgrade, and configure the Zowe server components or extensions manually or by using the following scripts: +* `zowe-install-component.sh` +* `zowe-upgrade-component.sh` (optional) +* `zowe-configure-component.sh`. +**Note:** The `zowe-upgrade-component.sh` script is currently an alpha release feature. As such, this script could present compatibility issues between the upgraded components and other Zowe components. + ## Install with `zowe-install-component.sh` (Technical Preview) -_Note: This section is for technical preview and we are happy to hear any feedback. Content in this section may be changed or improved in the future._ +**Notes:** +* This section is for technical preview. As such, we welcome feedback. Content in this section may be changed or improved in the future. -_Note: this feature is added with Zowe v1.19.0 release._ +* This feature is added with Zowe v1.19.0 release. -From Zowe v1.19.0, Zowe ships a `bin/zowe-install-component.sh` tool to help you install any Zowe server component (extension). Zowe core components are also installed with this tool. In order to be compatible with the tool, we recommend components follow [Zowe server component package format standard](packaging-zos-extensions.md#zowe-server-component-package-format). +From Zowe v1.19.0, Zowe ships a `bin/zowe-install-component.sh` tool to help you install any Zowe server component (extension). Zowe core components are also installed with this utility. In order to be compatible with the utility, we recommend components follow [Zowe server component package format standard](packaging-zos-extensions.md#zowe-server-component-package-format). -The tool can be executed from z/OS USS, and it takes these command line parameters: +Execute the utility from z/OS USS. Use the following command line parameters: -- **`-o|--component-file`**: (Required) Defines the path to the component package or directory. -- **`-c|--component-name`**: Specifies the name of the component. This parameter is optional if `NODE_HOME` is defined and the component has the manifest file. Otherwise, it's required. -- **`-i|--instance-dir`**: (Optional) Defines the path to the Zowe instance directory. When a value is defined, the script will also execute `bin/zowe-configure-component.sh` once it's installed. -- **`-d|--target-dir`**: (Optional) Defines the path to the installation target directory. For native components, the default value is `${ZOWE_ROOT_DIR}/components`. For non-native components, the script will check the value of the `ZWE_EXTENSION_DIR` variable. If the value is also empty, the script will fall back to the default target directory `/global/zowe/extensions`. -- **`-e|--auto-encoding`**: (Optional) Defines whether to automatically tag the encoding of the files that are shipped with the component. The default value is `auto`, which indicates that the script will determine whether the automatic tagging is needed or not. Note that the automatic tagging process is opinionated about which file extensions should be in which encoding. If this does not fit in your needs, a `pax` format is recommended to include the tagging information into your package. This option is only applicable for z/OS. Allowed values include: - * `yes`: automatically tag the encoding of the files. - * `no`: do not automatically tag encoding of the files. - * `auto`: tag only when manifest is in `ISO8859-1` encoding. -- **`-k|--core`**: This is an optional boolean. It defines whether this component is bundled into the Zowe package as a core component. -- **`-l|--logs-dir`**: (Optional) Specifies the path to the log directory. -- **`-f|--log-file`**: (Optional) Instead of writing independent log to a directory, you have option to append log to this log file specified. +- **`-o|--component-file`** -**Examples** + (Required) Defines the path to the component package or directory. +- **`-c|--component-name`** + + Specifies the name of the component. This parameter is optional if `NODE_HOME` is defined and the component has the manifest file, otherwise, this parameter is required. +- **`-i|--instance-dir`** + + (Optional) Defines the path to the Zowe instance directory. When a value is defined, the script also executes `bin/zowe-configure-component.sh` following installation. + +- **`-d|--target-dir`** + + (Optional) Defines the path to the installation target directory. For native components, the default value is `${ZOWE_ROOT_DIR}/components`. For non-native components, the script checks the value of the `ZWE_EXTENSION_DIR` variable. If the value is also empty, the script falls back to the default target directory `/global/zowe/extensions`. + +- **`-e|--auto-encoding`** + + (Optional) Defines whether to automatically tag the encoding of the files that are shipped with the component. The default value is `auto`, which indicates that the script determines whether the automatic tagging is needed or not. + + **Note:** The automatic tagging process is opinionated about which file extensions should be in which encoding. If this does not fit in your needs, a `pax` format is recommended to include the tagging information into your package. This option is only applicable for z/OS. The following list presents the allowed values: + * `yes` + + This option automatically tag the encoding of the files. + * `no` + + Do not automatically tag encoding of the files. + + * `auto` + + Tag only when manifest is in `ISO8859-1` encoding. -This command installs `my-zowe-component-1.2.3.pax` into `/global/zowe/extensions`. + - **`-k|--core`** + + This is an optional boolean. This parameter defines whether this component is bundled into the Zowe package as a core component. +- **`-l|--logs-dir`** + + (Optional) Specifies the path to the log directory. +- **`-f|--log-file`** + + (Optional) Instead of writing an independent log to a directory, you have the option to append log to this log file specified. + +**Examples:** + +The following command installs the `my-zowe-component-1.2.3.pax` into `/global/zowe/extensions`. ``` $ zowe-install-component.sh -o /path/to/my-zowe-component-1.2.3.pax ``` -This command installs `my-zowe-component-1.2.3.zip` into `/var/zowe/my-extensions` and also configures this component for the Zowe instance located at `/var/zowe/instance`. The installation and configuration logs will be written into `/var/zowe/instance/logs`. +The following command installs `my-zowe-component-1.2.3.zip` into `/var/zowe/my-extensions` and also configures this component for the Zowe instance located at `/var/zowe/instance`. The installation and configuration logs writes to `/var/zowe/instance/logs`. ``` $ zowe-install-component.sh \ @@ -44,30 +78,89 @@ $ zowe-install-component.sh \ -l /var/zowe/instance/logs ``` +## Upgrade with `zowe-upgrade-component.sh` (Technical Preview) + + + +**Notes:** +* This section is for technical preview. As such, we welcome any feedback. Content in this section may be changed or improved in the future. + +* _This feature is to be added with the Zowe v1.22.0 release._ + +From Zowe v1.22.0, Zowe ships a `bin/zowe-upgrade-component.sh` utility to help you upgrade any Zowe core component to the latest version available into the Zowe Artifactory. +By default, Zowe core components are not updated with this utility. To enable the upgrade functionality, set the optional boolean value `ZOWE_COMPONENTS_UPGRADE` to `true` as part of the installation configuration. Once the user has enabled this parameter, the `zowe-install.sh` +install script calls the `zowe-upgrade-component.sh` script. +The Zowe components get updated and then installed and configured using the `zowe-install-component.sh` and `zowe-configure-component.sh` scripts. +In order to be compatible with this utility, we recommend components follow the [Zowe server component package format standard](packaging-zos-extensions.md#zowe-server-component-package-format). + +The Zowe upgrade component utility can be executed from z/OS USS. You can use the following command line parameters: + +- **`-o|--component-file`** + + (Required) Defines the path to the component package or directory. + +- **`-l|--logs-dir`** + + (Optional) Specifies the path to the log directory. +- **`-f|--log-file`** + + (Optional) Instead of writing independent log to a directory, you have option to append log to this log file specified. + +**Examples:** + +``` +$ zowe-upgrade-component.sh -o /path/to/my-zowe-component-1.2.3.pax +``` + +This command upgrades `my-zowe-component-1.2.3.zip` to its latest version. The upgrade logs write to `/var/zowe/instance/logs`. + +``` +$ zowe-upgrade-component.sh \ + -o /path/to/my-zowe-component-1.2.3.zip \ + -l /var/zowe/instance/logs +``` + ## Configure with `zowe-configure-component.sh` (Technical Preview) _Note: This section is for technical preview and we are happy to hear any feedback. Content in this section may be changed or improved in the future._ -_Note: This feature is added with Zowe v1.19.0 release._ +**Note:** This feature is made available with the Zowe v1.19.0 release. -From Zowe v1.19.0, Zowe ships a `bin/zowe-configure-components.sh` tool to help you configure an installed Zowe server component (extension) for a Zowe instance. Zowe core components are also configured with this tool. In order to be compatible with the tool, we recommend components follow [Zowe server component package format standard](packaging-zos-extensions.md#zowe-server-component-package-format). +From Zowe v1.19.0, Zowe ships a `bin/zowe-configure-components.sh` utility to help you configure an installed Zowe server component (extension) for a Zowe instance. Zowe core components are also configured with this utility. In order to be compatible with the utility, we recommend components follow [Zowe server component package format standard](packaging-zos-extensions.md#zowe-server-component-package-format). You may not need to run this script directly if you have supplied `-i|--instance-dir` when you run `zowe-install-component.sh`. -The tool can be executed from z/OS USS, and it takes these command line parameters: +Execute this utility from z/OS USS. Use the following command line parameters: -- **`-c|--component-name`**: (Required) Specifies the name of the component. -- **`-i|--instance-dir`**: (Required) Defines the path to the Zowe instance directory. -- **`-d|--target-dir`**: (Optional) Defines the directory where the component is installed. For native components, the default value is `${ZOWE_ROOT_DIR}/components`. For non-native components, the script will check `ZWE_EXTENSION_DIR` if possible. Otherwise, it will fall back to the default target directory `/global/zowe/extensions`. -- **`-k|--core`**: This is an optional Boolean. It defines whether this component is bundled into the Zowe package as a core component. -- **`-l|--logs-dir`**: (Optional) Defines the path to the log directory. -- **`-f|--log-file`**: (Optional) Instead of writing independent log to a directory, you have option to append log to this log file specified. +- **`-c|--component-name`** -**Examples** + (Required) Specifies the name of the component. + +- **`-i|--instance-dir`** + + (Required) Defines the path to the Zowe instance directory. + +- **`-d|--target-dir`** + + (Optional) Defines the directory where the component is installed. For native components, the default value is `${ZOWE_ROOT_DIR}/components`. For non-native components, the script will check `ZWE_EXTENSION_DIR` if possible. Otherwise, it will fall back to the default target directory `/global/zowe/extensions`. + +- **`-k|--core`** + + This is an optional Boolean. It defines whether this component is bundled into the Zowe package as a core component. + +- **`-l|--logs-dir`** + + (Optional) Defines the path to the log directory. + +- **`-f|--log-file`** -This command configures `my-zowe-component` installed in `/global/zowe/extensions` for the Zowe instance located at `/var/zowe/instance`. + (Optional) Instead of writing independent log to a directory, you have option to append log to this log file specified. + +**Examples:** + +The following command configures `my-zowe-component` installed in `/global/zowe/extensions` for the Zowe instance located at `/var/zowe/instance`. ``` $ zowe-configure-component.sh \ @@ -75,7 +168,7 @@ $ zowe-configure-component.sh \ -i /var/zowe/instance ``` -This command configures `my-zowe-component` installed in `/var/zowe/my-extensions` for the Zowe instance located at `/var/zowe/instance`. The configuration logs will be written into `/var/zowe/instance/logs`. +The following command configures `my-zowe-component` installed in `/var/zowe/my-extensions` for the Zowe instance located at `/var/zowe/instance`. The configuration logs write to `/var/zowe/instance/logs`. ``` $ zowe-configure-component.sh \ @@ -105,21 +198,21 @@ The Zowe runtime directory delivers its core components in the `/co You can configure whether to start the Zowe core component or not with the `LAUNCH_COMPONENTS` variable defined in `/instance.env`. The value of this variable can be a comma-separated list of core component names. -**Note:** You can also use full USS path to the component `bin` directory which contains lifecycle scripts, but this behavior will be deprecated in next major release. +**Note:** You can also use the full USS path to the component `bin` directory which contains lifecycle scripts, but this behavior will be deprecated in next major release. ### Zowe extensions -It is suggested that you install all Zowe extension runtime programs into a single location. The suggested default extension directory is `/global/zowe/extensions`. Each extension should be represented with the extension name in this directory, either a directory or a symbolic link. This location should be defined as `ZWE_EXTENSION_DIR` in `/instance.env`. +We recommend that you install all Zowe extension runtime programs into a single location. The suggested default extension directory is `/global/zowe/extensions`. Each extension should be represented with the extension name in this directory, and use either a directory or a symbolic link. This location should be defined as `ZWE_EXTENSION_DIR` in `/instance.env`. -The Zowe launch script reads `EXTERNAL_COMPONENTS` defined in `/instance.env` to decide whether to start an extension. The value of `EXTERNAL_COMPONENTS` is a comma-separated list of extension names. +The Zowe launch script reads `EXTERNAL_COMPONENTS` defined in `/instance.env` to determine whether to start an extension. The value of `EXTERNAL_COMPONENTS` is a comma-separated list of extension names. -**Note:** You can also use full USS path to the extension `bin` directory which contains lifecycle scripts, but this behavior will be deprecated in next major release. +**Note:** You can also use the full USS path to the extension `bin` directory which contains lifecycle scripts. This behavior, however, is to be deprecated in next major release. -#### Example +**Example:** -The vendor MYVENDOR has a product named MYAPP that installs into `/usr/lpp/myvendor/myapp`. There is one Zowe extension shipped within it in the directory `/usr/lpp/myvendor/myapp/zowe-ext`. This subdirectory is a Zowe extension so they want it to be started and stopped with Zowe and run as an address space under the `ZWESVSTC` started task in the Zowe USS shell. +The vendor MYVENDOR has a product named MYAPP that installs into `/usr/lpp/myvendor/myapp`. There is one Zowe extension shipped within the product in the directory `/usr/lpp/myvendor/myapp/zowe-ext`. This subdirectory is a Zowe extension so that the product can be started and stopped with Zowe and run as an address space under the `ZWESVSTC` started task in the Zowe USS shell. -The directory `/usr/lpp/myvendor/myapp/zowe-ext` should include a `manifest.yaml` file to describe the extension. The script `/usr/lpp/myvendor/myapp/zowe-ext/bin/validate.sh` checks that the environment has been configured correctly and the script `/usr/lpp/myvendor/myapp/zowe-ext/bin/start.sh` starts the vendor application. The `/usr/lpp/myvendor/myapp/zowe-ext/manifest.yaml` should look like this: +The directory `/usr/lpp/myvendor/myapp/zowe-ext` should include a `manifest.yaml` file to describe the extension. The script `/usr/lpp/myvendor/myapp/zowe-ext/bin/validate.sh` checks that the environment is configured correctly and the script `/usr/lpp/myvendor/myapp/zowe-ext/bin/start.sh` starts the vendor application. The `/usr/lpp/myvendor/myapp/zowe-ext/manifest.yaml` should look like this: ```yaml name: myapp @@ -138,13 +231,57 @@ total 16 lrwxrwxrwx 1 23 Nov 11 2019 myapp -> /usr/lpp/myvendor/myapp/zowe-ext ``` -Also `myapp` will be added into the value of the `EXTERNAL_COMPONENTS` variable in `/instance.env`. +Also, `myapp` is added into the value of the `EXTERNAL_COMPONENTS` variable in `/instance.env`. ``` ZWE_EXTENSION_DIR=/global/zowe/extension EXTERNAL_COMPONENTS=some-other-extensions,myapp ``` -You might need to manually run the script `/bin/install-app.sh` if your component is a Desktop plug-in. Or you can choose to add this step to [Zowe component Configure lifecycle stage](lifecycling-with-zwesvstc.md#configure). +You might need to manually run the script `/bin/install-app.sh` if your component is a Desktop plug-in. Alternatively, you can choose to add this step to [Zowe component Configure lifecycle stage](lifecycling-with-zwesvstc.md#configure). When the Zowe instance is launched by running `/bin/zowe-start.sh`, it will read manifest `commands` instructions and call the `/usr/lpp/myvendor/myapp/zowe-ext/bin/start.sh` script. The started task will create an address space under `ZWESVSTC` for the vendor component. When the Zowe instance is stopped, the address space is terminated. + + +## Verify with `zowe-verify-component.sh` (Technical Preview) + + + +_Note: This section is for technical preview and we are happy to hear any feedback. Content in this section may be changed or improved in the future._ + +_Note: This feature is added with Zowe v1.22.0 release._ + +From Zowe v1.22.0, Zowe ships a `bin/zowe-verify-component.sh` tool to help you verify an installed Zowe server component (extension) for a Zowe instance. In order to be compatible with the tool, we recommend components follow [Zowe server component package format standard](packaging-zos-extensions.md#zowe-server-component-package-format) and define [Zowe component manifest](packaging-zos-extensions.md#zowe-component-manifest). + +The `zowe-verify-component.sh` script checks and verifies whether a specified component is up and running. You can use it to verify both core and external Zowe components. + +_IMPORTANT: To successfully verify whether a component service is registered on Zowe API Mediation Layer, this utility script requires authentication with a valid system user who has proper permission granted. For more information on the required user permission, please check [Protection of Service Information](../extend/extend-apiml/service-information.md#protection-of-service-information)._ + +The tool can be executed from z/OS USS, and it takes these command line parameters: + +- **`-c|--component-id`**: (Required) Specifies the name of the Zowe component that you want to verify. +- **`-i|--instance-dir`**: (Required) Specifies the path to the Zowe instance directory. +- **`-u|--username`**: (Required) Username of a specified user for the current system. +- **`-p|--password`**: (Required) Password of the specified user. + +**Examples** + +This command will verify the `external-zowe-component` installed in `/global/zowe/extensions` for the Zowe instance installed at `/var/zowe/instance`. + +``` +$ zowe-verify-component.sh \ + -c external-zowe-component \ + -i /var/zowe/instance \ + -u user \ + -p pass +``` + +You can also run the following commands to get the same results but instead of passing in values for the -u and -p parameters, you can use the export command. + +``` +$ export VERIFY_USER_NAME=user +$ export VERIFY_PASSWORD=pass +$ zowe-verify-component.sh \ + -c external-zowe-component \ + -i /var/zowe/instance +``` diff --git a/docs/extend/lifecycling-with-zwesvstc.md b/docs/extend/lifecycling-with-zwesvstc.md index 3a869272a9..3c9895342f 100644 --- a/docs/extend/lifecycling-with-zwesvstc.md +++ b/docs/extend/lifecycling-with-zwesvstc.md @@ -12,7 +12,7 @@ The Zowe UNIX System Services (USS) components are run as part of the started ta To start Zowe, the script `/bin/zowe-start.sh` is run from a USS shell. This uses a REXX program to launch the started task `ZWESVSTC`, passing the instance directory path as a parameter. It is the equivalent of using the TSO command `/S ZWESVSTC,INSTANCE='',JOBNAME=''`. The `ZWESVSTC` PROCLIB uses the program that creates a USS process and starts the script `/bin/internal/run-zowe.sh`. By using `BPXATSL` to start the USS process, all of the address spaces started under this shell are managed by SDSF. If the `zowe-start.sh` run `run-zowe.sh` directly, the USS processes will not run as a started task and will run under the user ID of whoever ran the `run-zowe.sh` script rather than the Zowe user ID of `ZWESVUSR`, likely leading to permission errors accessing the contents of the `` as well as the Zowe certificate. For these reasons, the `zowe-start.sh` script launches Zowe's USS process beneath the started task `ZWESVSTC`. -When `run-zowe.sh` is run in the USS shell that `BPXBATSL` creates, it executes the file `/instance.env`. This file sets a number of shell variables, such as `ROOT_DIR` that points to the directory with the ``, variables for all of the ports used by the Zowe components, and other configuration data. For more information, see [Reviewing the instance.env file](../user-guide/configure-instance-directory.md#reviewing-the-instance.env-file). +When `run-zowe.sh` is run in the USS shell that `BPXBATSL` creates, it executes the file `/instance.env`. This file sets a number of shell variables, such as `ROOT_DIR` that points to the directory with the ``, variables for all of the ports used by the Zowe components, and other configuration data. For more information, see [Updating the instance.env configuration file](../user-guide/configure-instance-directory.md#updating-the-instance-env-configuration-file). **Note:** diff --git a/docs/getting-started/cli-getting-started.md b/docs/getting-started/cli-getting-started.md index cc26764cd9..e0f25b5411 100644 --- a/docs/getting-started/cli-getting-started.md +++ b/docs/getting-started/cli-getting-started.md @@ -78,7 +78,10 @@ Most command groups require a `zosmf-profile`, but some plug-ins add their own p zowe profiles create zosmf-profile myprofile123 --host my.company.com --port 123 --user myusername123 --password mypassword123 ``` -**Note:** The port defaults to 443 if you omit the `--port` option. Specify a different port if your host system does not use port 443. +**Notes:** + +- The port defaults to 443 if you omit the `--port` option. Specify a different port if your host system does not use port 443. +- If z/OSMF is configured for high availability in Sysplex, create the CLI zosmf-profile with DVIPA address/hostname to ensure availability of REST services. For more information, see [Configuring z/OSMF high availability in Sysplex](../user-guide/systemrequirements-zosmf-ha.md). ### Using a zosmf profile diff --git a/docs/getting-started/diagrams/apiml-architecture b/docs/getting-started/diagrams/apiml-architecture new file mode 100644 index 0000000000..c9d6d723bf --- /dev/null +++ b/docs/getting-started/diagrams/apiml-architecture @@ -0,0 +1 @@ +7Vttc9s2DP41vnUf1tO75Y+Jk7bZuluW3G5rv+xoiZbYyaKPot/66wdK1Lsc27NkJkuSO1sEQUnEA4AASI/M6WL7kaFl+Cv1cTQyNH87Mm9GhqE7YxO+BGWXUdyJkxECRnzJVBIeyXcsiZqkroiPkxojpzTiZFknejSOscdrNMQY3dTZ5jSqP3WJAtwiPHooalP/JD4PJVV3JmXHJ0yCUD7aNeT8FihnljNJQuTTTYVk3o7MKaOUZ1eL7RRHQni5XLJxH/b0Fi/GcMyPGWDh352b4JeF//fDnX+zmk1mD3c/6YZ8Ob7LZ4x9EIBsUsZDGtAYRbcl9ZrRVexjcVsNWiXPZ0qXQNSB+A1zvpNoohWnQAr5IpK9eEv4X2L4e1u2vlR6brbyzmljlzdiznbZIMPO21+qneW4tJUPzCYoZrVXcJKU0BXz8FPSkgqIWID5E3xWAS/YBaYLDO8D4xiOECfr+nsgqaBBwVdiCBcSxhMgNdRAWsBTw+a9fQCdBITJr4ShAiGmMc5pH4iYtioEDZUIyvuuUbSSTxoZTgSvez1jcBXwVCZNyh8JZi3kweksU8A8ThkwbULC8eMSpULagMuuozgHoU9pJFhhtOnb2PWtFBFG/8GVHteYmY5TYLPGjOPt0+i0pSkHmI70kHKJsGRzU/rbnBRWPG0+qn/xmy/QJ6pyicaLcIktg7q6vwPCNCJiwk2061ieaDIIu3Ovy2Qcz8WzeT8mY7kHTUY3LmkzZkvCNyTxKExSvPUjZmsC8utT0PM5drxOQfvjyUzT+hG00RC07qiWtG4p9U4V31R6qgPeSR+dFBL06J2sI72TqXS5d9UGbEOtHQel7pwpdTn0nhLhxHOTta26ybZukWmNHFViB0Eo2lXYloIhOf05pSpkdywVo5jjGSuZmthkwODeR0mYvpuuxvR17UwtPC8ysVV68/w6Q3N8pDsfQAm+rRbLfM6IeTkle/8xNGP6MxAkt0cXxHsm6jPpw4ed6nocu+F6NLuqiQf5bVsbDe+qnLNVuwr0QRU5K+fSXPO/ZF3jk5bOmiV4EUoS4jWMIX/yPWYEAMBMXUxkq9Bsa9LQbFt7UrPN8ZP8w2i2lGAl2fmION6goVKdy5RhmjnlM0h1lC6O9UKMdqxLqHkE/YBH6NGs7SPNWmmqY7csRxZiEEcRDXq1mrnr4e4Cwcy1LXugAkHRVmY1TlvGKx7CdIgHCNN4JN7GQSKaus4+gSJYKCPfc45kiIqNLf47S2PpnxhBY16hZ3/DuDf1QOnnB0iXruScGPr36N7GL8G9FVu9qio5xkmrz5HxqAIUz90t6KWgk8eW+2JPyz6PP/cs+/ht/Un+gbI2JeVllYWiY3VSbaFovCdyerlbK+09LNULcqEyz6IQ//y8t3ukpYxVGorbMpTvcJ/fHoF2z6i/8vrd771MltG0FdtQbSuT/WKOQCPhE6/To4BFJqG9+/ooukE+8AEZCfuxVyQus/PuPDsk8iihAsUUeSGJg6HKUUoErb4cZbTX4OzMlYY8DycJTkQina7KpdKvCSqonjxuor273ULmLbC4gtZXuhGc0893bYMA+fFmqFQVuoyVqghJEopIEIuVAR4pysjXAg3ioehKdiyI76crWBf6df0QablcvyY9OTStEdu2wXU7sLUGw7a9bBzAVhB4CHIKQrgqCsCvFL+Javza61H9iNcbjp04QohS97K6YiDN9mrWSHQ0D6UVSk4ZTr8BMnFXQTy88P1fgXQah2i7ypuXBbJ9irncJXuDsAvChk/VbdUQGi0IH3BAEpCd8Jri5ob2CUO+OcMoq6y9CqCai19XaNoFlDkYUO3jt29ACYGbdaDMianYotpHBx7oioMIxM/ainThtUUhVmPxMjvOs1/WoNob1W84dWRtR6Ztw+HU3uyepqEFSEwMLmpSEEP+IFwhXmPRvQnTL7aK4yzWoPN5hf2VwNk8FmgpDzj2Z+GHjzCg+hGGV4JhM4ErbK1/k4Rm+WvlbL+x/M23efsv \ No newline at end of file diff --git a/docs/getting-started/diagrams/apiml-architecture.png b/docs/getting-started/diagrams/apiml-architecture.png new file mode 100644 index 0000000000..772db8f111 Binary files /dev/null and b/docs/getting-started/diagrams/apiml-architecture.png differ diff --git a/docs/getting-started/freqaskques.md b/docs/getting-started/freqaskques.md index 06680e88ba..6327982ef2 100644 --- a/docs/getting-started/freqaskques.md +++ b/docs/getting-started/freqaskques.md @@ -97,7 +97,7 @@ To get up and running with the Zowe CLI component quickly, see [Zowe CLI quick s -Prerequisites vary by component used, but in most cases the primary prerequisites are Java and NodeJS on z/OS and the z/OS Management Facility enabled and configured. For a complete list of software requirements listed by component, see [System requirements](../user-guide/systemrequirements.md). +Prerequisites vary by component used, but in most cases the primary prerequisites are Java and NodeJS on z/OS and the z/OS Management Facility enabled and configured. For a complete list of software requirements listed by component, see [System requirements for z/OS components](../user-guide/systemrequirements-zos.md) and [System requirements for Zowe CLI](../user-guide/systemrequirements-cli.md). diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md index 3c76ef3a2f..3b48c9af00 100644 --- a/docs/getting-started/overview.md +++ b/docs/getting-started/overview.md @@ -119,7 +119,7 @@ For information about extending the functionality of Zowe CLI by installing plug **More Information:** - - [System requirements for Zowe CLI](../user-guide/systemrequirements.md) + - [System requirements for Zowe CLI](../user-guide/systemrequirements-cli.md) - [Installing Zowe CLI](../user-guide/cli-installcli.md) @@ -147,6 +147,7 @@ The API Mediation Layer provides a single point of access for mainframe service * Consistent Access: API routing and standardization of API service URLs through the Gateway component provides users with a consistent way to access mainframe APIs at a predefined address. * Dynamic Discovery: The Discovery Service automatically determines the location and status of API services. * High-Availability: API Mediation Layer is designed with high-availability of services and scalability in mind. +* Caching Service: This feature is designed for Zowe components in a high availability configuration. It supports the High Availability of all components within Zowe, allowing components to be stateless by providing a mechanism to offload their state to a location accessible by all instances of the service, including those which just started. * Redundancy and Scalability: API service throughput is easily increased by starting multiple API service instances without the need to change configuration. * Presentation of Services: The API Catalog component provides easy access to discovered API services and their associated documentation in a user-friendly manner. Access to the contents of the API Catalog is controlled through a z/OS security facility. * Encrypted Communication: API ML facilitates secure and trusted communication across both internal components and discovered API services. @@ -154,7 +155,7 @@ The API Mediation Layer provides a single point of access for mainframe service #### API Mediation Layer architecture The following diagram illustrates the single point of access through the Gateway, and the interactions between API ML components and services: -![API Mediation Layer Architecture diagram](./diagrams/service-relationship-diagram.png) +![API Mediation Layer Architecture diagram](./diagrams/apiml-architecture.png) #### Components The API Layer consists of the following key components: @@ -179,6 +180,10 @@ The API Catalog is the catalog of published API services and their associated do Access to the API Catalog can be protected with an Enterprise z/OS Security Manager such as IBM RACF, CA ACF2, or CA Top Secret. Only users who provide proper mainframe credentials can access the Catalog. Client authentication is implemented through the z/OSMF API. +**Caching Service** + +It provides an API in high-availability mode which offers the possibility to store, retrieve and delete data associated with keys. The service will be used only by internal Zowe applications and will not be exposed to the internet. + #### Onboarding APIs Essential to the API Mediation Layer ecosystem is the API services that expose their useful APIs. Use the following topics to discover more about adding new APIs to the API Mediation Layer and using the API Catalog: @@ -192,6 +197,12 @@ Essential to the API Mediation Layer ecosystem is the API services that expose t To learn more about the architecture of Zowe, see [Zowe architecture](zowe-architecture.md). +### Zowe Launcher + +Provides an advanced launcher for Zowe components in a high availability configuration. It performs the following operations: + - Stopping the Zowe server using the `STOP` (or `P`) operator command + - Stopping and starting specific Zowe components without restarting the entire Zowe using `MODIFY` (or `F`) operator command + ## Zowe Third-Party Software Requirements and Bill of Materials - [Third-Party Software Requirements (TPSR)](../appendix/tpsr.md) diff --git a/docs/getting-started/summaryofchanges.md b/docs/getting-started/summaryofchanges.md index 5a8b8f417a..52c1ec9263 100644 --- a/docs/getting-started/summaryofchanges.md +++ b/docs/getting-started/summaryofchanges.md @@ -2,8 +2,9 @@ Learn about what is new, changed, or removed in Zowe™. -Zowe Version 1.21 and earlier releases include the following enhancements, release by release. +Zowe Version 1.22 and earlier releases include the following enhancements, release by release. +- [Version 1.22.0 LTS (June 2021)](#version-1-22-0-lts-june-2021) - [Version 1.21.0 LTS (April 2021)](#version-1-21-0-lts-april-2021) - [Version 1.20.1 LTS (March 2021)](#version-1-20-1-lts-march-2021) - [Version 1.20.0 LTS (March 2021)](#version-1-20-0-lts-march-2021) @@ -33,8 +34,127 @@ Zowe Version 1.21 and earlier releases include the following enhancements, relea - [Version 1.0.1 (March 2019)](#version-1-0-1-march-2019) - [Version 1.0.0 (February 2019)](#version-1-0-0-february-2019) +## Version 1.22.0 LTS (June 2021) + +Welcome to the Version 1.22.0 release of Zowe! You can find some of the highlights included in this release in the **Notable changes** section. To see a full list of release enhancements and fixes, see **New features and enhancements** and **Bug fixes**. + +**Release demo:** Join the Zowe System Demo on June 21 to see a demo of what's new in this release, and ask the community questions. Check out the [Zowe calendar](https://lists.openmainframeproject.org/g/zowe-dev/calendar) for detailed call-in information. + +**Download v1.22.0 build:** Want to try new features as soon as possible? You can download the v1.22.0 build from [Zowe.org](https://www.zowe.org/download.html). + +### Notable changes + +**Configure Zowe for high availability (Technical Preview)** + +You can deploy Zowe in Parallel Sysplex for high availability with several enhancements shipped with v1.22.0 release. + +- By deploying Zowe in Sysplex, comparing to a single instance of Zowe, you are configuring and starting multiple Zowe instances. See how [Zowe architecture](zowe-architecture.md) is changed with high availability. +- In addition to the `instance.env` file that is used to configure Zowe, now you can use a new YAML configuration file `zowe.yaml` to configure multiple Zowe instances in more granular level. See [Updating the zowe.yaml configuration file](../user-guide/configure-instance-directory.md#updating-the-zowe-yaml-configuration-file-technical-preview) for more information. +- The new `ZWESLSTC` started task can monitor status of microservices running within Zowe and restart the missing microservice(s) when needed. See [Configure ZWESLSTC to run Zowe High Availability under ZWESVUSR user ID](../user-guide/configure-zos-system.md#configure-zweslstc-to-run-zowe-high-availability-under-zwesvusr-user-id) for more information. + +To get started with Zowe high availability, see [Zowe high availability installation roadmap](../user-guide/install-ha-sysplex.md). + +**New tool for verifying an installed Zowe server component (Technical Preview)** + +You can verify an installed Zowe server component (extension) for a Zowe instance by using the `bin/zowe-verify-component.sh` tool that Zowe ships in this release. The `zowe-verify-component.sh` tool checks and verifies whether a specified component is up and running. You can use it to verify both core and external Zowe components. This tool is for technical preview now and we are happy to hear any feedback. + +For more information, see [Verify with `zowe-verify-component.sh`](../extend/install-configure-zos-extensions.md#verify-with-zowe-verify-componentsh-technical-preview). + +### New features and enhancements + +#### Zowe API Mediation Layer + +- Deterministic routing based on the provided headers is now available. Clients can now specify which instance of a service the user should be routed to. This enables reusability of underlying resources such as LPARs associated with a specific service instance (#1496) ([ed91f25](https://github.com/zowe/api-layer/commit/ed91f25)), closes [#1496](https://github.com/zowe/api-layer/issues/1496). +- Basic authentication via Websocket is now fully supported (#1482) ([112da99](https://github.com/zowe/api-layer/commit/112da99)), closes [#1482](https://github.com/zowe/api-layer/issues/1482). +- Passwords can be changed via SAF. An endpoint is exposed allowing users to change passwords using this API ML endpoint (#1471) ([3f3c2af](https://github.com/zowe/api-layer/commit/3f3c2af)), closes [#1471](https://github.com/zowe/api-layer/issues/1471). +- A self-service application is now available that can run in the infrastructure of the user to verify whether certificates are properly created and configured (#1441) ([e694c0f](https://github.com/zowe/api-layer/commit/e694c0f)), closes [#1441](https://github.com/zowe/api-layer/issues/1441) + +#### Zowe App Server + +- Plugins can push state out to the Caching Service for high availability storage via a storage API, available to dataservices as `remoteStorage` +- Plugins can push state out to the In-Memory Storage via a storage API, available to dataservices as `localStorage` +- Add "remoteStorage" pointer to dataservice struct, for accessing high availability remote storage in addition to or alternatively to local storage. +- Plugins can push state out to the Caching Service for high availability storage via a improved storage API, available to dataservices as `context.storage` +- Storage API V2 added which has parameters to specify whether plugin cache and state should be stored local to a worker, in the cluster, or remote for high availability +- Decrease verbosity and duplication of startup logs. Log messages omitted have been moved to debug messaging. +- Change missing swagger warning message to debug as it is a warning for developers, not for end users. + +#### Zowe CLI + +The following enhancements were made to the **FTP Plug-in**: +- Added retcode in the output of the view job-status-by-jobid and submit command to be consistent with ZOSMF plugin. +- Added --rdw to download dataset command to download variable-length dataset. + +#### Zowe Explorer + +- Added the refresh data set member names option. You can now retrieve a new list of members from the mainframe. [#1343](https://github.com/zowe/vscode-extension-for-zowe/pull/1343) +- Added the best practice documentation for error handling. [#1335](https://github.com/zowe/vscode-extension-for-zowe/pull/1335) +- Added the developer guide for adding commands to core Zowe Explorer menus. [#1332](https://github.com/zowe/vscode-extension-for-zowe/pull/1332) +- Standardized context group names. [#1340](https://github.com/zowe/vscode-extension-for-zowe/pull/1340) + +#### Zowe JES/MVS/USS Explorers + +The following enhancements were added to the **MVS Explorer**: +- Updated material ui +- Updated webpack build and dev config + +The following enhancements were added to the **USS Explorer**: +- Updated material ui from 0.18 to 4.x, react from v15 to v16 +- Updated webpack config for local build config +- Updated packages for security updates + +### Bug fixes + +#### Zowe installation and configuration + +- Several issues related to `ZWEKRING` [#2089](https://github.com/zowe/zowe-install-packaging/issues/2089) and `ZWESSOTK` [#2144](https://github.com/zowe/zowe-install-packaging/issues/2144) sample JCLs are fixed with [#2101](https://github.com/zowe/zowe-install-packaging/pull/2101). +- Fixed [issue #2120](https://github.com/zowe/zowe-install-packaging/issues/2120) about handling external certificate authorities when using keyring. +- Fixed several issues described in [#1976](https://github.com/zowe/zowe-install-packaging/issues/1976) related to install and configuration when z/OSMF is absent. + +#### Zowe API Mediation Layer + +- Use the apiml.service.id in the API Catalog as used in other services. (#1475) ([7bc8f99](https://github.com/zowe/api-layer/commit/7bc8f99)), closes [#1475](https://github.com/zowe/api-layer/issues/1475) +- Change the registration to use the correct hostname in `instanceId` (#1473) ([1d6caa8](https://github.com/zowe/api-layer/commit/1d6caa8)), closes [#1473](https://github.com/zowe/api-layer/issues/1473) +- The HTTP client is not closed when generating a passticket. The ZAAS client can now reuse connections and provide correct login with passtickets (#1470) ([ed9f929](https://github.com/zowe/api-layer/commit/ed9f929)), closes [#1470](https://github.com/zowe/api-layer/issues/1470). +- Configurable jwt alias at startup via environment variable (#1442) ([0e3df7a](https://github.com/zowe/api-layer/commit/0e3df7a)), closes [#1442](https://github.com/zowe/api-layer/issues/1442) +- Use the actual hostname instead of the one provided by Spring Cloud (#1434) ([6b8c38a](https://github.com/zowe/api-layer/commit/6b8c38a)), closes [#1434](https://github.com/zowe/api-layer/issues/1434) +- Distinguish lib and fat jars (#1398) ([f771a40](https://github.com/zowe/api-layer/commit/f771a40)), closes [#1398](https://github.com/zowe/api-layer/issues/1398) +- Accept list of Discovery services in the Catalog. If the Catalog fails to contact to the Discovery service, the Catalog tries to contact another service from the list (#1376) ([42ae70d](https://github.com/zowe/api-layer/commit/42ae70d)), closes [#1376](https://github.com/zowe/api-layer/issues/1376) + +#### Zowe App Server + +- Prefer internal IP/hostname over external one when stating to discovery server where app-server is located. For many users there is no behavior difference because the values are the same. +- Dataset contents API doesn't skip empty records while reading a dataset +- ZSS now takes into account `relativeTo` attribute when loading plugin dlls +- Dataservice loading did not warn if program control was missing, which is essential, so plugin loading would fail silently in that case. +- Fix /server/agent route when using APIML +- Fix issue with CORS rejection when accessing zss through APIML gateway + +#### Zowe CLI + +The follow bug was fixed in **Zowe CLI**: +- Ensured that the like field will always be added to all allocate like requests. [#1017](https://github.com/zowe/zowe-cli/pull/1017) + +The following bugs were fixed in the **Secure Credential Store Plug-in**: +- Updated the Keytar and prebuild-install dependencies to make offline install possible for npm@7 users. +- Updated the Keytar dependency to v7.7 to be compatible with Node.js v16. + +The following bugs were fixed in the **Imperative CLI Framework**: +- Fixed active command tree item not updating in web help when scrolling. [#425](https://github.com/zowe/imperative/issues/425) +- Fixed main page of web help not staying scrolled to top of page when loaded. [#525](https://github.com/zowe/imperative/issues/525) + +The following bug was fixed in the **FTP Plug-in**: +- Expose meta data for Zowe Explorer FTP extension. + +#### Zowe Explorer + +- Fixed the error message that popped up when accessing profiles from Favorites. [#1344](https://github.com/zowe/vscode-extension-for-zowe/pull/1344) +- Fixed the issue that prevented the Allocate Like feature from working correctly. [#1322](https://github.com/zowe/vscode-extension-for-zowe/pull/1322) + ## Version 1.21.0 LTS (April 2021) +Check out [this blog](https://www.openmainframeproject.org/blog/2021/05/06/zowe-1-21-release-highlights-demo-video) that summarizes some of the major enhancements and changes for this release. You can also watch a [video](https://youtu.be/lL4oyaj0Ohs) on Open Mainframe Project’s Youtube Channel see a demo of what's new in this release. + ### New features and enhancements #### Zowe installation and configuration @@ -135,6 +255,8 @@ The following bugs were fixed in the **FTP Plug-in**: ## Version 1.20.0 LTS (March 2021) +Check out [this blog](https://www.openmainframeproject.org/blog/2021/04/14/zowe-1-20-release-available) that summarizes some of the major enhancements and changes for this release. + ### New features and enhancements #### Zowe API Mediation Layer @@ -274,7 +396,6 @@ You can now start the API Mediation Layer independently of other Zowe components ### New features and enhancements #### Zowe API Mediation Layer - - The connection limit of the Gateway has been configured to support multiple long-running requests by service. [#843](https://github.com/zowe/api-layer/issues/843) - The size of API Mediation Layer has been reduced to fit within 150MB. [#909](https://github.com/zowe/api-layer/issues/909) @@ -305,13 +426,10 @@ You can now start the API Mediation Layer independently of other Zowe components - Existing code highlighters have been reorganized in order to improve their readability. Additionally, a new code highlighter for the REXX language has been added. This new code highlighter detects files and datasets wherein the files should end with the .rexx prefix, but the datasets may contain the rexx or exec qualifiers. [#181](https://github.com/zowe/zlux-editor/pull/181) #### Zowe Explorer - + - Updated Keytar and Jest dev deps for Node 14. #### Zowe JES/MVS/USS Explorers - The following features and enhancements were added to the **JES Explorer**: - Introduced the menu shortcuts and confirmation dialog before canceling or purging the job for JES explorer. [#235](https://github.com/zowe/explorer-jes/pull/235) @@ -393,7 +511,7 @@ The following enhancement was added to the **FTP Plug-in**: #### Zowe JES/MVS/USS Explorers - + The following features and enhancements were added to the **JES Explorer**: - Added webdevSever proxy setting in webpack.config.js to enable https for local development. @@ -401,14 +519,11 @@ The following features and enhancements were added to the **JES Explorer**: ### Bug Fixes #### Zowe API Mediation Layer - + - ZaasJwtService enhancement on JWT parsing and error handling. [#897](https://github.com/zowe/api-layer/issues/897) - Upgrade dependencies for the Enablers. [#933](https://github.com/zowe/api-layer/issues/933) #### Zowe App Server - - The zss server log verbosity seen when using the TN3270 desktop app has been reduced. [#188](https://github.com/zowe/zowe-common-c/pull/188) - Keep-alive parsing has been temporarily disabled to patch a memory leak. A permanent fix that will allow the use of keep-alive parsing is scheduled to be implemented in the next release. [#186](https://github.com/zowe/zowe-common-c/pull/186) @@ -446,7 +561,7 @@ For more information about the Node.js and Python SDKs, see [Using Zowe SDKs](.. The following features and enhancements were added. #### Zowe installation - + - You can now start ZSS independent of the Zowe Application Framework server by specifying the `LAUNCH_COMPONENT_GROUP "ZSS"`. If `DESKTOP` is specified instead of `ZSS`, ZSS will still be included as a prerequisite to the Application Framework server. [#1632](https://github.com/zowe/zowe-install-packaging/pull/1632) - Zowe instance configuration script (`zowe-configure-instance.sh`) can now skip checking for Node.js by passing in the `-s` flag since Node.js may not be needed if the components to be launched don't require it. [#1677](https://github.com/zowe/zowe-install-packaging/pull/1677) - The `run-zowe.sh` script can also skip the checking for Node.js by setting the environment variable `SKIP_NODE=1` for the cases where the components to be launched don't require Node.js. @@ -454,14 +569,12 @@ The following features and enhancements were added. - A new documentation chapter [Upgrading the z/OS System for Zowe](../user-guide/upgrade-zos-system.md) has been included, that describes the steps to take when upgrading an existing Zowe installation. #### Zowe API Mediation Layer - + - Multiple versions of one API are now presented in the Catalog if configured to do so. Users can now switch between different versions within the Catalog to see differences in API documentation between versions. [#844](https://github.com/zowe/api-layer/issues/844) - Setting `APIML_DEBUG_MODE_ENABLED` in `instance.env` is properly passed on to the all API ML services. [#901](https://github.com/zowe/api-layer/issues/901) #### Zowe App Server - + - ZSS no longer requires NodeJS for its configure.sh script. - Added support for DER-encoded X.509 certificates. - You are now able to change tags for all files in the directory excluding subdirectories. For example, `POST /unixfile/chtag/u/user/tmp?codeset=1047&type=text&recursive=false` should change tags only for files in `u/user/tmp` without changing tags for files in subdirectories. [#176](https://github.com/zowe/zowe-common-c/pull/176) @@ -477,13 +590,6 @@ https://github.com/zowe/zss/edit/staging/CHANGELOG.md --> #### Zowe CLI - - - - - - - The following enhancements were added to the **core CLI**: - Zowe CLI was tested and confirmed to be compatible with Node.js v14. @@ -513,7 +619,7 @@ The following enhancement was made to enable support for Node.js v14 for the **I - Added login and logout functions for base profiles. You can now log in to API Mediation Layer and generate a token for your base profile. [#914](https://github.com/zowe/vscode-extension-for-zowe/issues/914) #### Zowe JES/MVS/USS Explorers - + The following features and enhancements were added to the **JES Explorer**: - Added ability to refresh content of an open job output file via context menu entry on the job file [#549](https://github.com/zowe/zlux/issues/549) @@ -528,7 +634,7 @@ The following bugs were fixed. - Updated API paths for the API ML in the API Catalog to use the service id in front. [#853](https://github.com/zowe/api-layer/issues/853) #### Zowe App Server - + - Make use of external certificate authorities referenced during keystore setup time. - ZSS startup would issue warnings about failure to write yml files for APIML in the case APIML was not also being used. - Bugfix: In previous versions, external certificate authorities were not registered with the app server properly and would sometimes contribute to a SELF_SIGNED_CERT_IN_CHAIN error when using the mediation layer. This issue has been resolved by adding external CA certs to the app-server CA array. [#138](https://app.zenhub.com/workspaces/community-5c93e02fa70b456d35b8f0ed/issues/zowe/zlux-app-server/138) @@ -565,13 +671,13 @@ Additional TN3270 terminal configuration options can now be specified within the The following features and enhancements were added. #### Zowe installation - + - Moved explorer-ui-server out of explorers into new `shared` folder under Zowe Runtime Directory. [#1545](https://github.com/zowe/zowe-install-packaging/pull/1545), [#207](https://github.com/zowe/explorer-jes/pull/207), [#37](https://github.com/zowe/explorer-ui-server/pull/37) - Created `zowe-setup-keyring-certificates.env` and removed the overloaded properties from `zowe-setup-certificates.env` to try to simplify the user experience when setting up certificates in the keyring and USS keystore modes. [#1603](https://github.com/zowe/zowe-install-packaging/issues/1603) #### Zowe API Mediation Layer - + - ZAAS Client can now use HTTP so that the Application Transparent Transport Layer Security (AT-TLS) can be used for communication to ZAAS. [#813](https://github.com/zowe/api-layer/issues/813) - Implemented the logout functionality in ZAAS Client. [#808](https://github.com/zowe/api-layer/issues/808) - Added a more helpful and actionable description to message ZWEAM511E, which occurs when API ML does not trust the certificate provided by the service. [#818](https://github.com/zowe/api-layer/issues/818) @@ -595,18 +701,13 @@ The following features and enhancements were added. - The app server can now read and use keys, certificates, and certificate authorities contained with PKCS12 files. This is in addition to existing support for PEM-encoded files as well as z/OS keyrings. [#244](https://github.com/zowe/zlux-server-framework/pull/244) #### Zowe CLI - - - - - The following enhancements were added to the **core CLI**: - Added a `--pattern` option to the `zowe files list all-members` command. The option lets you restrict returned member names to only names that match a given pattern. The argument syntax is the same as the "pattern" parameter of the ISPF LMMLIST service. [#810](https://github.com/zowe/zowe-cli/issues/810) - Added new options `--lrecl` and `--recfm` to the `zos-files create` command. Use these options to specify a logical record length and record format for data sets that you create. [#788](https://github.com/zowe/zowe-cli/issues/788) #### Zowe Explorer - + - Added the Allocate Like feature. [#904](https://github.com/zowe/vscode-extension-for-zowe/issues/904) - Added the ability to disable/enable profile validation. [#922](https://github.com/zowe/vscode-extension-for-zowe/issues/922) - Added the ability to access other profiles during profile validation. [#953](https://github.com/zowe/vscode-extension-for-zowe/issues/953) @@ -663,7 +764,7 @@ In previous versions, the environment `arch` and `os` fields were incorrect. Thi ``` #### Zowe CLI - + The following bug was fixed in the **FTP plug-in for Zowe CLI**: - Fixed an issue where the `view spool-file-by-id` command retrieved incorrect contents. [#61](https://github.com/zowe/zowe-cli-ftp-plugin/issues/61) @@ -678,8 +779,6 @@ The following bug was fixed in the **FTP plug-in for Zowe CLI**: ### Notable changes - - **Keyring support** Prior to v1.15, the Zowe z/OS components were only able to use a certificate held in a USS Java KeyStore. In v1.15, the Zowe z/OS components can now use a certificate that is held in a z/OS keyring as described in [Configuring Zowe certificates in a keyring](../user-guide/configure-certificates-keyring.md). @@ -696,12 +795,10 @@ By default, the API Gateway uses z/OSMF as an authentication provider. With the ### New features and enhancements - - The following features and enhancements were added: #### Zowe API Mediation Layer - + - The API Path Pattern now supports `serviceId` as the first element. This improves the consistency of the URL when processing through the Gateway or outside of the Gateway. [#688](https://github.com/zowe/api-layer/issues/688) - The SAF Provider can now be used as a possible authentication provider. This removes the API ML dependency on z/OSMF for authentication enabling SAF to obtain the JWT. [#472](https://github.com/zowe/api-layer/issues/472) - The Swagger URL is now provided for z/OSMF. This URL provides full documentation containing the Try It Out functionality if the z/OSMF version supports the Swagger endpoint. Alternatively, the URL provides the info endpoint to directly enable access to Zowe endpoints. [#665](https://github.com/zowe/api-layer/issues/665) @@ -742,25 +839,19 @@ A new endpoint has been added to the Agent API. This new endpoint will return a #### Zowe CLI The following features and enhancements were added to the **core CLI**: - - Added a `--responseTimeout` option to the z/OS Files APIs, CLI commands, and z/OSMF profiles. Specify `--responseTimeout <###>` to set the number of seconds that the TSO servlet request runs before a timeout occurs. The default is 30 seconds. You can set the option to 5 - 600 seconds (inclusive). [#760](https://github.com/zowe/zowe-cli/issues/760) - Added the `--encoding` option for the `zowe zos-files upload dir-to-pds` command. This option lets you upload multiple members with a single command. [#764](https://github.com/zowe/zowe-cli/issues/764) The following features and enhancements were added to the **Imperative CLI Framework**: - - Added support for dynamically generated cookie names. Updated `AbstractSession.storeCookie()` to process cookie names that are not fully known at build-time. [#431](https://github.com/zowe/imperative/pull/431) - Added the SSO Callback function, which allows applications to call their own functions while validating session properties (that is, host, port, user, password, token, and so on). The callback option is named `getValuesBack`. [#422](https://github.com/zowe/imperative/issues/422) The following features and enhancements were added to the **Secure Credential Store Plug-in**: - - Added the `scs revert` command. Use the command to revert securely stored credentials in your user profiles to be stored in plain text. [#22](https://github.com/zowe/zowe-cli-scs-plugin/issues/22) - Changed the `scs update` and `scs revert` commands so that they fail if Secure Credential Manager is not enabled. [#23](https://github.com/zowe/zowe-cli-scs-plugin/pull/23) - - - #### Zowe JES/MVS/USS Explorers The following features and enhancements were added to the **JES Explorer**: @@ -778,7 +869,7 @@ The following features and enhancements were added to the **MVS Explorer** and * The following bugs were fixed. #### Zowe API Mediation Layer - + - Fixed SSL validation when Eureka is running in HTTP mode. When the scheme is HTTP, SSL configuration is not verified since it is not used. [#792](https://github.com/zowe/api-layer/issues/792) - Fixed a problem in error handling when no api-doc is available. Now a specific return code and message is generated when a problem occurs when obtaining or transforming the api-doc. [#571](https://github.com/zowe/api-layer/issues/571) @@ -802,9 +893,6 @@ The following bugs were fixed in the **core CLI**: The following bug was fixed in the **Imperative CLI Framework**: - Fixed an issue with `ConnectionPropsForSessCfg` where the user would be prompted for user/password even if a token was present. [#436](https://github.com/zowe/imperative/pull/436) - - - #### Zowe JES/MVS/USS Explorers The following bugs were fixed in the **JES Explorer**: @@ -823,7 +911,6 @@ The following bugs were fixed in the **USS Explorer**: ## Version 1.14.0 LTS (August 2020) ### Notable changes - **Zowe Node APIs** @@ -837,14 +924,12 @@ If the contents of the Zowe runtime directory have been modified, then it may re ### New features and enhancements - - The following features and enhancements were added. #### Zowe installation - If you are upgrading to Zowe v1.14 from a previous release, -and the value of `ZOWE_EXPLORER_HOST` does not match the host and domain that you put into your browser to access Zowe, you must update your configuration due to updated referrer-based security. See [System Requirements](../user-guide/systemrequirements.md#important_note_for_users_upgrading_to_v1.14) for information on updating your configuration. +and the value of `ZOWE_EXPLORER_HOST` does not match the host and domain that you put into your browser to access Zowe, you must update your configuration due to updated referrer-based security. See [Important note for users upgrading to v1.14](../user-guide/upgrade-zos-system.md#important-note-for-users-upgrading-to-v114) for information on updating your configuration. - Allow the user to verify the authenticity of a Zowe driver. The script `zowe-verify-authenticity.sh` will check that a Zowe `ROOT_DIR` for an installed release matches the contents for when that release was created, which assists with support and troubleshooting. To verify pre-1.14 releases, the script and its associated code are available [separately](https://github.com/zowe/zowe-install-packaging/blob/staging/files/fingerprint.pax) (see [#1552](https://github.com/zowe/zowe-install-packaging/issues/1552)). For more information, see the new topic [Verify Zowe Runtime Directory](../troubleshoot/verify-fingerprint.md) that describes the operation of the script. - Allow multiple domains (names/IP Addresses) when generating certificates. This also includes SMP/E `HOLDDATA` for the affected function `Zowe Configuration`. [#1511](https://github.com/zowe/zowe-install-packaging/issues/1511) - Included z/OSMF workflows for Zowe z/OS configuration. [#1527](https://github.com/zowe/zowe-install-packaging/issues/1527) @@ -1265,8 +1350,6 @@ The following bugs were fixed: ### New features and enhancements - - The following features and enhancements were added: #### API Mediation Layer diff --git a/docs/getting-started/user-roadmap-apiml.md b/docs/getting-started/user-roadmap-apiml.md index 874668c759..fb1d8e6f49 100644 --- a/docs/getting-started/user-roadmap-apiml.md +++ b/docs/getting-started/user-roadmap-apiml.md @@ -24,7 +24,7 @@ The following definition of skill levels about Zowe assist you with gathering th > Zowe skill level: Beginner -- [**System requirements**](../user-guide/systemrequirements.md) +- [**System requirements**](../user-guide/systemrequirements-zos.md) Review this topic to ensure that your system meets the requirements for installing the API Mediation Layer. API Mediation Layer is one of the server-side components. diff --git a/docs/getting-started/user-roadmap-app-framework.md b/docs/getting-started/user-roadmap-app-framework.md index a25631aad4..3044a551a7 100644 --- a/docs/getting-started/user-roadmap-app-framework.md +++ b/docs/getting-started/user-roadmap-app-framework.md @@ -28,7 +28,7 @@ The following definition of skill levels about Zowe will help you gather most re > Zowe skill level: Beginner -- [**System requirements**](../user-guide/systemrequirements.md) +- [**System requirements**](../user-guide/systemrequirements-zos.md) Review this topic to ensure that your system meets the requirements for installing the Zowe Application Framework. Zowe Application Framework is one of the server-side components. diff --git a/docs/getting-started/user-roadmap-zowe-cli.md b/docs/getting-started/user-roadmap-zowe-cli.md index 095e2b47b5..bbe769cd23 100644 --- a/docs/getting-started/user-roadmap-zowe-cli.md +++ b/docs/getting-started/user-roadmap-zowe-cli.md @@ -41,7 +41,7 @@ The following definition of skill levels about Zowe will help you gather most re > Zowe skill level: Beginner -- [**System requirements**](../user-guide/systemrequirements.md#zowe-cli-requirements) +- [**System requirements**](../user-guide/systemrequirements-cli.md) Review this topic to ensure that your system meets the requirements for installing Zowe CLI. diff --git a/docs/images/common/zowe-ha-install-roadmap.png b/docs/images/common/zowe-ha-install-roadmap.png new file mode 100644 index 0000000000..8f3f28f1ff Binary files /dev/null and b/docs/images/common/zowe-ha-install-roadmap.png differ diff --git a/docs/images/common/zowe-ha-install-roadmap.pptx b/docs/images/common/zowe-ha-install-roadmap.pptx new file mode 100644 index 0000000000..e776b9a78d Binary files /dev/null and b/docs/images/common/zowe-ha-install-roadmap.pptx differ diff --git a/docs/images/common/zowe-zos-install-diagram.pptx b/docs/images/common/zowe-zos-install-diagram.pptx index 705111d7bb..2b807082dd 100644 Binary files a/docs/images/common/zowe-zos-install-diagram.pptx and b/docs/images/common/zowe-zos-install-diagram.pptx differ diff --git a/docs/images/zosmf/zOSMF-HA.png b/docs/images/zosmf/zOSMF-HA.png new file mode 100644 index 0000000000..55fb7be1d7 Binary files /dev/null and b/docs/images/zosmf/zOSMF-HA.png differ diff --git a/docs/images/zowe-zos-install-diagram.png b/docs/images/zowe-zos-install-diagram.png deleted file mode 100644 index 6b6a5d39d5..0000000000 Binary files a/docs/images/zowe-zos-install-diagram.png and /dev/null differ diff --git a/docs/troubleshoot/cli/known-cli.md b/docs/troubleshoot/cli/known-cli.md index 420a7c7041..4f42bc307a 100644 --- a/docs/troubleshoot/cli/known-cli.md +++ b/docs/troubleshoot/cli/known-cli.md @@ -29,7 +29,7 @@ To correct this behavior, verify the following: - Node.js and NPM are installed. - PATH contains the correct path to the NodeJS folder. -**More Information:** [System requirements for Zowe CLI](../../user-guide/systemrequirements.md) +**More Information:** [System requirements for Zowe CLI](../../user-guide/systemrequirements-cli.md) ## `npm install -g `Command Fails Due to an EPERM Error diff --git a/docs/troubleshoot/troubleshoot-apiml-error-codes.md b/docs/troubleshoot/troubleshoot-apiml-error-codes.md index 09502bb79b..2c674fc554 100644 --- a/docs/troubleshoot/troubleshoot-apiml-error-codes.md +++ b/docs/troubleshoot/troubleshoot-apiml-error-codes.md @@ -45,10 +45,10 @@ The following error message codes may appear on logs or API responses. Use the f ### ZWEAO105W - Gateway HTTP Client per-route connection limit of %s has been reached for the '%s' route. + Gateway HTTP Client per-route connection limit (maxConnectionsPerRoute) of %s has been reached for the '%s' route. **Reason:** - + Too many concurrent connection requests were made to the same route. **Action:** @@ -57,7 +57,7 @@ The following error message codes may appear on logs or API responses. Use the f ### ZWEAO106W - Gateway Http Client total connection limit of %s has been reached. + Gateway HTTP Client total connection limit (maxTotalConnections) of %s has been reached. **Reason:** @@ -111,7 +111,7 @@ The following error message codes may appear on logs or API responses. Use the f **Reason:** - The Message service is requested to create a message with an invalid key. + Message service is requested to create a message with an invalid key. **Action:** @@ -123,7 +123,7 @@ The following error message codes may appear on logs or API responses. Use the f **Reason:** - The Message service is requested to create a message with an invalid text format. + Message service is requested to create a message with an invalid text format. **Action:** @@ -153,7 +153,7 @@ The following error message codes may appear on logs or API responses. Use the f Refer to the specific message to identify the exact problem. Possible causes include: - - An incorrect security algorithm + - Incorrect security algorithm - The keystore is invalid or corrupted - The certificate is invalid or corrupted @@ -379,9 +379,21 @@ The following error message codes may appear on logs or API responses. Use the f Please submit an issue with this message. +### ZWEAT403E + + The user is not authorized to the target resource: %s + + **Reason:** + + The service has accepted the authentication of the user but the user does not have access rights to the resource. + + **Action:** + + Contact your security administrator to give you access. + ### ZWEAT601E - z/OSMF service name not found. Set parameter apiml.security.auth.zosmfServiceId to your service ID. + z/OSMF service name not found. Set parameter apiml.security.auth.zosmf.serviceId to your service ID. **Reason:** @@ -389,7 +401,31 @@ The following error message codes may appear on logs or API responses. Use the f **Action:** - Ensure that the parameter apiml.security.auth.zosmfServiceId is correctly entered with a valid z/OSMF service ID. + Ensure that the parameter apiml.security.auth.zosmf.serviceId is correctly entered with a valid z/OSMF service ID. + +### ZWEAT602E + + The SAF provider `endpoint` supports only the resource class 'ZOWE', but the current one is '%s' + + **Reason:** + + The parameter `apiml.security.authorization.provider` is set to `endpoint` + + **Action:** + + Change the SAF provider to another one to use this endpoint + +### ZWEAT603E + + Endpoint `%s` is not properly configured + + **Reason:** + + The application cannot call the endpoint to check the SAF resource of the user + + **Action:** + + Verify the state of ZSS and IZS, then check if parameters `apiml.security.authorization.endpoint.*` are matching. ## Security client messages @@ -545,11 +581,11 @@ The following error message codes may appear on logs or API responses. Use the f **Reason:** - The authorization header was empty or null. + The authorization header was empty or null **Action:** - Try again with a valid authorization header. + Try again with a valid authorization header ### ZWEAS170E @@ -557,7 +593,7 @@ The following error message codes may appear on logs or API responses. Use the f **Reason:** - General exception. There is more information in the message. + General exception. There are more pieces of information in the message **Action:** @@ -569,11 +605,11 @@ The following error message codes may appear on logs or API responses. Use the f **Reason:** - Unable to generate a PassTicket. + Unable to generate PassTicket. **Action:** - Verify that the secured signon (PassTicket) function and application ID is configured properly by referring to Using PassTickets in the guide for your security provider. + Verify that the secured signon (PassTicket) function and application ID is configured properly by referring to Using PassTickets in the guide for your security provider ### ZWEAS401E @@ -581,11 +617,11 @@ The following error message codes may appear on logs or API responses. Use the f **Reason:** - There was no JWT token provided for the generation of the PassTicket. + There was no JWT token provided for the generation of the PassTicket **Action:** - Ensure that you are passing a JWT token for PassTicker generation. + Ensure that you are passing JWT token for PassTicker generation ### ZWEAS404E @@ -593,19 +629,19 @@ The following error message codes may appear on logs or API responses. Use the f **Reason:** - The Gateway Service doe not respond. + Gateway service does not respond. **Action:** - Ensure that the Gateway Service is up and that the path to the gateway service is properly set. + Ensure that the Gateway service is up and that the path to the gateway service is properly set. ### ZWEAS417E - The application name wasn't found + The application name was not found **Reason:** - The application id provided for the generation of the PassTicket was not recognized by the security provider. + The application id provided for the generation of the PassTicket was not recognized by the security provider **Action:** @@ -617,7 +653,7 @@ The following error message codes may appear on logs or API responses. Use the f **Reason:** - The JWT token is not valid. + The JWT token is not valid **Action:** @@ -629,7 +665,7 @@ The following error message codes may appear on logs or API responses. Use the f **Reason:** - The Zaas Client configuration does not contain the path to the trust store. + The Zaas Client configuration does not contain the path to the trust store **Action:** @@ -641,7 +677,7 @@ The following error message codes may appear on logs or API responses. Use the f **Reason:** - The Zaas Client configuration does not contain the path to the key store. + The Zaas Client configuration does not contain the path to the key store **Action:** @@ -669,7 +705,7 @@ The following error message codes may appear on logs or API responses. Use the f **Action:** - Ensure that both provided paths are resolved to valid trust store and valid key store. + Ensure that both provided paths are resolved to valid trust store and valid key store ## Discovery service messages @@ -707,7 +743,7 @@ The following error message codes may appear on logs or API responses. Use the f **Action:** - Review the static API definition directories and their setup. The static definition directories are specified as a launch parameter to a Discovery service jar. The property key is: `apiml.discovery.staticApiDefinitionsDirectories`. + Review the static API definition directories and their setup. The static definition directories are specified as a launch parameter to a Discovery service jar. The property key is: `apiml.discovery.staticApiDefinitionsDirectories` ### ZWEAD701E @@ -775,6 +811,18 @@ The following error message codes may appear on logs or API responses. Use the f ## Gateway service messages +### ZWEAG500E + + Client certificate is missing in request. + + **Reason:** + + No client certificate is present in the HTTPS request. + + **Action:** + + Properly configure client to send client certificate. + ### ZWEAG700E No instance of the service '%s' found. Routing will not be available. @@ -883,6 +931,18 @@ The following error message codes may appear on logs or API responses. Use the f Make sure that the service is running and is accessible by the URL provided in the message. +### ZWEAG710E + + Load balancer does not have available server for client: %s + + **Reason:** + + The service is not available. It might be removed by the Circuit Breaker or by requesting specific instance that is not available + + **Action:** + + Try the request later or remove the request for specific instance. + ### ZWEAG100E Authentication exception: '%s' for URL '%s' @@ -981,15 +1041,15 @@ The following error message codes may appear on logs or API responses. Use the f ### ZWEAG108E - z/OSMF instance '%s' not found or incorrectly configured. + z/OSMF instance '%s' not found or incorrectly configured. Gateway is shutting down. **Reason:** - The Gateway could not find the z/OSMF instance from the Discovery Service. + The Gateway could not find the z/OSMF instance from the Discovery Service or it could not communicate with the provided z/OSMF instance. **Action:** - Ensure that the z/OSMF instance is configured correctly and that it is successfully registered to the Discovery Service. + Ensure that the z/OSMF instance is configured correctly and that it is successfully registered to the Discovery Service and that the API Mediation Layer can communicate with provided z/OSMF instance. ### ZWEAG109E @@ -1250,4 +1310,19 @@ The following error message codes may appear on logs or API responses. Use the f Check the specific exception for troubleshooting. +### ZWEAC708E + + The API base path for service %s was not retrieved. %s + + **Reason:** + + The API base path for service was not retrieved. An empty path will be used. + + **Action:** + + Refer to the specific printed message. Possible causes include: + - The URI ... is not valid. Ensure the service is providing a valid url. + - Not able to select a route for url ... of service ... The original url is used. If this is a problem, check the routing metadata of the service. + - The path ... of service URL ... is not valid. Ensure the service is providing the correct path. + diff --git a/docs/user-guide/api-mediation/api-gateway-configuration.md b/docs/user-guide/api-mediation/api-gateway-configuration.md index 299f1de610..c6a8fe7131 100644 --- a/docs/user-guide/api-mediation/api-gateway-configuration.md +++ b/docs/user-guide/api-mediation/api-gateway-configuration.md @@ -21,6 +21,7 @@ Follow the procedures in the following sections to customize Gateway parameters * [Connection limits](#connection-limits) * [Replace or remove catalog with another service](#replace-or-remove-catalog-with-another-service) * [API Mediation Layer as a standalone component](#api-mediation-layer-as-a-standalone-component) + * [SAF resource checking](#saf-resource-checking) ## Prefer IP Address for API Layer services @@ -49,6 +50,32 @@ the following procedure to switch to SAF. Authentication requests now utilize SAF as the authentication provider. API ML can run without z/OSMF present on the system. +### Change password with SAF provider + +Update the user password using the SAF Authentication provider. To use this functionality, add the parameter `newPassword` on the login endpoint `/gateway/api/v1/auth/login`. The Gateway service returns a valid JWT with the response code `204` as a result of successful password change. The user is then authenticated and can consume APIs through the Gateway. If it is not possible to change the password for any reason, the response code is `401`. + +Use a `POST` REST call against the URL `/gateway/api/v1/auth/login`: + + ``` + { + "username" : "", + "password" : "", + "newPassword" : "" +} +``` + +**Note:** +It is a common practice to set the limit for changing the password in the ESM. This value is set by the parameter `MINCHANGE` for `PASSWORD`. The password can be changed once. Subsequently, it is necessary to wait the specified time period before changing the password again. + +**Example:** + +`MINCHANGE=120` + +where: + +* **`120`** + + Specifies the number of days before the password can be reset ## Gateway retry policy To change the Gateway retry policy, edit properties in the `/components/gateway/bin/start.sh` file: @@ -64,7 +91,7 @@ To change this default configuration, include the following parameters: * **ribbon.OkToRetryOnAllOperations** - Specifies whether to retry all operations for this service. The default value is `false`. In this case, only `GET` requests are retried if they return a response code that is listed in `ribbon.retryableStatusCodes`. Setting this parameter to `true` enables retry requests for all methods which return a response code listed in `ribbon.retryableStatusCodes`. + Specifies whether to retry all operations for this service. The default value is `false`. In this case, only `GET` requests are retried if they return a response code that is listed in `ribbon.retryableStatusCodes`. Setting this parameter to `true` enables retry requests for all methods which return a response code listed in `ribbon.retryableStatusCodes`. **Note:** Enabling retry can impact server resources due to request body buffering. @@ -78,11 +105,8 @@ To change this default configuration, include the following parameters: ## Gateway client certificate authentication -**Note:** - Beginning with release 1.19 LTS, it is possible to authenticate using client certificates. The feature is functional and tested, but automated testing on various security systems is not complete. As such, the feature is provided as a beta release for early preview. If you would like to offer feedback using client certificate authentication, please create an issue against the api-layer repository. Client Certificate authentication will move out of Beta once test automation is fully implemented across different security systems. - Use the following procedure to enable the feature to use a client certificate as the method of authentication for the API Mediation Layer Gateway. **Follow these steps:** @@ -102,7 +126,7 @@ Use the following procedure to enable the feature to use a client certificate as 3. Change the following property if user mapping is provided by an external API: - * **APIML_GATEWAY_EXTERNAL_MAPPER** + * **APIML_GATEWAY_EXTERNAL_MAPPER** **Note:** Skip this step if user mapping is not provided by an external API. @@ -116,7 +140,7 @@ Use the following procedure to enable the feature to use a client certificate as 4. Add the following property if the Zowe runtime userId is altered from the default `ZWESVUSR`: - * **APIML_GATEWAY_MAPPER_USER** + * **APIML_GATEWAY_MAPPER_USER** **Note:** Skip this step if the Zowe runtime userId is not altered from the default `ZWESVUSR`. @@ -202,7 +226,7 @@ Use the following procedure to change the number of concurrent connections. 2. Find the property `APIML_MAX_CONNECTIONS_PER_ROUTE` and set the value to an appropriate positive integer. 3. Find the property `APIML_MAX_TOTAL_CONNECTIONS` and set the value to an appropriate positive integer. -## Replace or remove catalog with another service +## Replace or remove the Catalog with another service By default, the API Mediation Layer contains API Catalog as a service showing available services. As the API Mediation Layer can be successfully run without this component it is possible to replace or remove the service from the Gateway home page and health checks. The following section describes the behavior of the Gateway home page and health checks. @@ -228,8 +252,9 @@ A value can also be applied to `API_GATEWAY_CATALOG_ID`. A possible dashboard that could appear in place of the API Catalog **Notes:** + - If the application contains the `homePageUrl` and `statusPageRelativeUrl`, then the full set of information is displayed. -- If the application contains the `homePageUrl` the link is displayed without the `UP` information +- If the application contains the `homePageUrl` the link is displayed without the `UP` information. - If the application contains the `statusPageRelativeUrl` then `UP` or `DOWN` is displayed based on the `statusPage` without the link. Use the following procedure to change or replace the Catalog service: @@ -242,7 +267,7 @@ Use the following procedure to change or replace the Catalog service: - Set the value to `none` to remove the Catalog service. - Set the value to the ID of the service that is onboarded to the API Mediation Layer. -# API Mediation Layer as a standalone component +## API Mediation Layer as a standalone component You can start the API Mediation Layer independently of other Zowe components. By default, the Gateway, Zowe System Services, and Virtual Desktop start when @@ -260,3 +285,106 @@ Once Zowe is installed, use the following procedure to limit which components st 3. Restart `Zowe&trade`. To learn more about the related section of the environment file, see [Creating and configuring the Zowe instance directory](../configure-instance-directory.md#component-groups). We recommend you open this page in a new tab. + +## SAF Resource Checking + +The API ML can check for the authorization of the user on certain endpoints. Access to a SAF resource is checked with ESM. + +Verification of the SAF resource is provided by the following three providers: + +- **`endpoint`** + + This is the highest priority provider, such as a REST endpoint call (ZSS or similar one). This option is disabled by default. In Zowe, ZSS has the API to check for SAF resource authorization. + +- **`native`** + + The Native JZOS classes from Java are used to determine SAF resource access. This is the default provider. + +- **`dummy`** + + This is the lowest priority provider. This is the dummy implementation and is defined in a file. + +**Note:** Verification of the SAF resource uses the first available provider based on the specified priority. The default configuration resolves to the native provider. + +You can select a specific provider by specifying the `APIML_SECURITY_AUTHORIZATION_PROVIDER` key in the `instance.env` file. Use the parameter value to +strictly define a provider. If verification is disabled, select the `endpoint` option. + +**Follow these steps:** + +1. Open the file `/instance.env`. +2. Add the property `APIML_SECURITY_AUTHORIZATION_PROVIDER` and set desired value. +3. Restart `Zowe&trade`. + +**Examples:** +``` +APIML_SECURITY_AUTHORIZATION_PROVIDER=endpoint +``` +**Note:** To configure the `endpoint` provider, add the following additional property: +`APIML_SECURITY_AUTHORIZATION_ENDPOINT_ENABLED=true` +``` +APIML_SECURITY_AUTHORIZATION_PROVIDER=native +``` +``` +APIML_SECURITY_AUTHORIZATION_PROVIDER=dummy +``` + +To use the endpoint provider, customize the URL corresponding to the SAF resource authorization. By default, the ZSS API is configured and used. + +**Follow these steps:** + +1. Open the file `/instance.env`. +2. Modify the property `APIML_SECURITY_AUTHORIZATION_ENDPOINT_URL` and set desired value. + The default value for ZSS API is `https://${ZOWE_EXPLORER_HOST}:${GATEWAY_PORT}/zss/api/v1/saf-auth` +3. Restart `Zowe&trade`. + +### Checking providers + +#### REST endpoint call + +The REST provider calls the external API to retrieve information about access rights. To enable the feature outside of the mainframe, such as when running in Docker, you can use a REST endpoint call using the `GET` method: + +- Method: `GET` +- URL: `{base path}/{userId}/{class}/{entity}/{level}` +- Response: +```json5 + { + "authorized": "{true|false}", + "error": "{true|false}", + "message": "{message}" + } +``` +**Note:** For more information about this REST endpoint call, see [ZSS implementation](https://github.com/zowe/zss/blob/master/c/authService.c). + +#### Native + +The Native provider is the easiest approach to use the SAF resource checking feature on the mainframe. + +Enable this provider when classes `com.ibm.os390.security.PlatformAccessControl` and `com.ibm.os390.security.PlatformReturned` +are available on the classpath. This approach uses the following method described in the IBM documentation: [method](https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/com.ibm.java.zsecurity.api.80.doc/com.ibm.os390.security/com/ibm/os390/security/PlatformAccessControl.html?view=kc#checkPermission-java.lang.String-java.lang.String-java.lang.String-int-). + +**Note:** Ensure that the version of Java on your system has the same version of classes and method signatures. + +#### Dummy implementation + +The Dummy provider is for testing purpose outside of the mainframe. + +Create the file `saf.yml` and locate it in the folder, where is application running or create file `mock-saf.yml` in the +test module (root folder). The highest priority is to read the file outside of the JAR. A file (inner or outside) has to exist. + +The following YAML presents the structure of the file: + +```yaml + safAccess: + {CLASS}: + {RESOURCE}: + - {UserID} +``` + +**Notes**: +- Classes and resources are mapped into a map, user IDs into a list. +- The load method does not support formatting with dots, such as shown in the following example: + **Example:** {CLASS}.{RESOURCE} + Ensure that each element is separated. +- The field `safAccess` is not required to define an empty file without a definition. +- Classes and resources cannot be defined without the user ID list. +- When a user has multiple definitions of the same class and resource, only the most privileged access level loads. diff --git a/docs/user-guide/configure-caching-service-ha.md b/docs/user-guide/configure-caching-service-ha.md new file mode 100644 index 0000000000..161cee5716 --- /dev/null +++ b/docs/user-guide/configure-caching-service-ha.md @@ -0,0 +1,58 @@ +# Configuring the Caching Service for HA + +Zowe uses the Caching Service to centralize the state data persistent in high availability (HA) mode. The Caching Service supports three storage methods: `inMemory`, `VSAM` and `redis`. + +- **inMemory** + + This storage method is designed for quick start of the service and should be used only for single instance scenario and development or test purpose. Do not use it in production or high availability scenario. + + To use this method, leave the `ZWE_CACHING_SERVICE_PERSISTENT` configuration blank in the `instance.env` configuration file. When this method is enabled, the Caching Service will not persist any data. Also, if you have multiple instances of Caching Service, the data will not be shared across these instances. + +- **VSAM** + + **Note:** Performance issues related to the VSAM data set have been observed, so it is recommended that you use this storage method for light workload. If heavy workload is expected on Zowe components, it is recommended that you use the `redis` storage method instead. + + To use this method, + 1. Set the value of `ZWE_CACHING_SERVICE_PERSISTENT` to `VSAM` in the `instance.env` configuration file. + 2. Create a VSAM data set. See [Creating a VSAM data set](#creating-a-vsam-data-set) for instructions. + 3. In `instance.env`, configure `ZWE_CACHING_SERVICE_VSAM_DATASET` with the VSAM data set you created. + +- **redis** + + To enable this method, set the value of `ZWE_CACHING_SERVICE_PERSISTENT` to `redis` in the `instance.env` configuration file. + +. + +## Creating a VSAM data set + +You can use the `ZWECSVSM` JCL to create a VSAM data set and define required security configurations. The `ZWECSVSM` JCL is provided as part of the PDS sample library `SZWESAMP` that is delivered with Zowe. + +Before you submit the `ZWECSVSM` JCL, you must customize it and review it with a system programmer who is familiar with z/OS VSAM data set and storage. + +The following variables are available in the JCL. + +- `#dsname` variable + + This is the data set name that the `ZWECSVSM` JCL will create. Replace all occurrences of `#dsname` with the data set name that you want to specify. This data set name is the value for `ZWE_CACHING_SERVICE_VSAM_DATASET` in `instance.env`. + +- `MODE` variable + + This specifies whether you would like to use [Record Level Sharing (RLS)](https://www.ibm.com/support/pages/vsam-record-level-sharing-rls-overview) for your VSAM data set. `RLS` is recommended for Sysplex deployment. + + ``` + // SET MODE=NONRLS RLS or NONRLS + ``` + +- `#storclas` variable + + If you use the `RLS` mode, a storage class is required. Replace `#storclas` with your desired storage class name. + +- `#volume` variable + + If you set to use the `NONRLS` mode, a storage volume is required. Replace `#volume` with you desired storage volume. + +**Procedure** + +1. Customize the `ZWECSVSM` JCL. Edit the variables at the beginning and in the middle of the JCL. + +2. Submit the `ZWECSVSM` JCL to create a VSAM data set diff --git a/docs/user-guide/configure-certificates-keystore.md b/docs/user-guide/configure-certificates-keystore.md index d6abee64cc..d008cf38e8 100644 --- a/docs/user-guide/configure-certificates-keystore.md +++ b/docs/user-guide/configure-certificates-keystore.md @@ -159,7 +159,7 @@ Before you submit the JCL, you must [customize it](#customizing-the-zwessotk-jcl The `ZWESSOTK` JCL contains commands for the following scenarios: - Defining security requirements needed by following steps and using the `PKCS#11` token. -- (Optional) Creation of a locally generated certificated can be used as JWT secret. +- Creation of a locally generated certificated can be used as JWT secret if it does not already exist. - Creation of `PKCS#11` token. - Binding JWT secret certificate to the `PKCS#11` token. @@ -190,7 +190,9 @@ This is the `PKCS#11` token name will be created by `ZWESSOTK` JCL. This token n ### Enabling SSO -To enable SSO, you should run `zowe-setup-certificates.sh` with values of `PKCS11_TOKEN_NAME` and `PKCS11_TOKEN_LABEL` matching what you defined in `ZWESSKTK` JCL. +To enable SSO, you should run `zowe-setup-certificates.sh` with values of `PKCS11_TOKEN_NAME` and `PKCS11_TOKEN_LABEL` matching what you defined in `ZWESSOTK` JCL. + +If you have already Zowe certificate generated, you should edit the `zowe-certificates.env` file in the `KEYSTORE_DIRECTORY` directory, set the `PKCS11_TOKEN_NAME` and `PKCS11_TOKEN_LABEL` with values which you have defined in `ZWESSOTK` JCL, and restart Zowe. If you are upgrading from an old version of Zowe, you can diff --git a/docs/user-guide/configure-instance-directory.md b/docs/user-guide/configure-instance-directory.md index 482cda62e9..c4b0178a33 100644 --- a/docs/user-guide/configure-instance-directory.md +++ b/docs/user-guide/configure-instance-directory.md @@ -4,14 +4,29 @@ The Zowe instance directory or `` contains configuration dat **Note: The creation of an instance directory will set default values for users who want to run all Zowe z/OS components. If you are using Docker, you must make a small configuration change to disable the components on z/OS that will instead run in Docker.** -The instance directory `/bin` contains a number of key scripts - - `zowe-start.sh` is used to start the Zowe runtime by launching the `ZWESVSTC` started task. - - `zowe-stop.sh` is used to stop the Zowe runtime by terminating the `ZWESVSTC` started task. - - `zowe-support.sh` can be used to capture diagnostics around the Zowe runtime for troubleshooting and off-line problem determination, see [Capturing diagnostics to assist problem determination](../troubleshoot/troubleshoot-diagnostics.md). +## Introduction + +The purpose of the instance directory is to hold information in the z/OS File System (zFS) that is created (such as log files) or modified (such as preferences) or configured (such as port numbers) away from the zFS runtime directory for Zowe. This allows the runtime directory to be read-only and to be replaced when a new Zowe release is installed, with customizations being preserved in the instance directory. + +Multiple instance directories can be created and used to launch independent Zowe runtimes from the same Zowe runtime directory. + +The Zowe instance directory contains a file `instance.env` that stores the Zowe configuration data. The data is read each time Zowe is started. You can modify `instance.env` to configure the Zowe runtime. See [Updating the instance.env configuration file](#updating-the-instanceenv-configuration-file) for more information. + +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. See [Updating the zowe.yaml configuration file (Technical Preview)](#updating-the-zowe-yaml-configuration-file-technical-preview) for more information. + +The instance directory `/bin` contains other key scripts as follows: +- `zowe-start.sh` is used to start the Zowe runtime by launching the `ZWESVSTC` started task. +- `zowe-stop.sh` is used to stop the Zowe runtime by terminating the `ZWESVSTC` started task. +- `zowe-support.sh` can be used to capture diagnostics around the Zowe runtime for troubleshooting and off-line problem determination, see [Capturing diagnostics to assist problem determination](../troubleshoot/troubleshoot-diagnostics.md). + +**High availability considerations:** + +- If you plan to run Zowe in Sysplex for high availability, the instance directory should be placed in a shared USS file system. This way, all Zowe instances within the Sysplex can read and write to the same instance directory. +- `zowe.yaml` is required if you want to start Zowe in high availability mode. ## Prerequisites -Before creating an instance directory, ensure that you have created a keystore directory that contains the Zowe certificate. For more information about how to create a keystore directory, see [Creating Zowe certificates](configure-certificates.md). Also, ensure that you have already configured the z/OS environment. For information about how to configure the z/OS environment, see [Configuring the z/OS system for Zowe](configure-zos-system.md). +Before creating an instance directory, ensure that you have created a keystore directory that contains the Zowe certificate. See [Creating Zowe certificates](configure-certificates.md) for instructions. Also, ensure that you have already configured the z/OS environment. See [Configuring the z/OS system for Zowe](configure-zos-system.md) for instructions. ## Creating an instance directory @@ -23,45 +38,70 @@ Navigate to the Zowe runtime directory `` and execute the following /bin/zowe-configure-instance.sh -c ``` -Multiple instance directories can be created and used to launch independent Zowe runtimes from the same Zowe runtime directory. - -The Zowe instance directory contains a file `instance.env` that stores configuration data. The data is read each time Zowe is started. - -The purpose of the instance directory is to hold information in the z/OS File System (zFS) that is created (such as log files) or modified (such as preferences) or configured (such as port numbers) away from the zFS runtime directory for Zowe. This allows the runtime directory to be read-only and to be replaced when a new Zowe release is installed, with customizations being preserved in the instance directory. - If you have an instance directory that is created from a previous release of Zowe 1.8 or later and are installing a newer release of Zowe, then you should run `zowe-configure-instance.sh -c ` pointing to the existing instance directory to have it updated with any new values. The release documentation for each new release will specify when this is required, and the file `manifest.json` within each instance directory contains information for which Zowe release it was created from. -In order to allow the `ZWESVSTC` started task to have permission to acces the contents of the `` the `zowe-configure-instance.sh` script sets the group ownership of the top level directory and its child to be `ZWEADMIN`. If a different group is used for the `ZWESVSTC` started task you can specify this with the optional `-g` argument, for example. +In order to allow the `ZWESVSTC` started task to have permission to access the contents of the `` the `zowe-configure-instance.sh` script sets the group ownership of the top level directory and its child to be `ZWEADMIN`. If a different group is used for the `ZWESVSTC` started task you can specify this with the optional `-g` argument, for example. ```sh /bin/zowe-configure-instance.sh -c -g ``` -## Reviewing the instance.env file +## Updating the instance.env configuration file -To operate Zowe, a number of zFS folders need to be located for prerequisites on the platform. Default values are selected when you run `zowe-configure-instance.sh`. You might want to modify the values. +To operate Zowe, a number of zFS folders need to be located for prerequisites on the platform. Default values are selected when you run `zowe-configure-instance.sh`. You might want to modify the values. -### Component groups - -`LAUNCH_COMPONENT_GROUPS`: This is a comma-separated list of which z/OS microservice groups are started when Zowe launches. - - `GATEWAY` will start the API mediation layer that includes the API catalog, the API gateway, and the API discovery service. These three address spaces are Apache Tomcat servers and use the version of Java on z/OS as determined by the `JAVA_HOME` value. In addition to the mediation layer, the z/OS Explorer services are included here as well. - - `DESKTOP` will start the Zowe desktop that is the browser GUI for hosting Zowe applications such as the 3270 Terminal emulator or the File Explorer. It will also start ZSS. The Zowe desktop is a node application and uses the version specified by the `NODE_HOME` value. - - `ZSS` will start the ZSS server without including the Desktop and Application Framework server. This can be used with Docker so that you do not run servers on z/OS that will already be running within Docker. This may also be useful if you want to utilize ZSS core features or plug-ins without needing the Desktop. ZSS is a pre-requisite for the Zowe desktop, so when the `DESKTOP` group is specified then the zss server will be implicitly started. For more information on the zssServer and the technology stack of the Zowe servers see [Zowe architecture](../getting-started/zowe-architecture.md). - - Vendor products may extend Zowe with their own component group that they want to be lifecycled by the Zowe `ZWESVSTC` started task and run as a Zowe sub address space. To do this, specify the fully qualified directory provided by the vendor that contains their Zowe extension scripts. This directory will contain a `start.sh` script **(required)** that is called when the `ZWESVSTC` started task is launched, a `configure.sh` script **(optional)** that performs any configuration steps such as adding iFrame plug-ins to the Zowe desktop, and a `validate.sh` script **(optional)** that can be used to perform any pre-launch validation such as checking system prerequisites. For more information about how a vendor can extend Zowe with a sub address space, see the [Extending](../extend/extend-apiml/onboard-overview.md) section. +**Contents in this section** -**Note: If you are using Docker, it is recommended to remove GATEWAY and DESKTOP from LAUNCH_COMPONENT_GROUPS by setting `LAUNCH_COMPONENT_GROUPS=ZSS`. This will prevent duplication of servers running both in Docker and on z/OS.** +- [Zowe prerequisites](#zowe-prerequisites) +- [Domain, Hostname and IP Address](#domain-hostname-and-ip-address) +- [Component groups](#component-groups) +- [Keystore configuration](#keystore-configuration) +- [Address space names](#address-space-names) +- [Ports](#ports) + - [Terminal ports](#terminal-ports) +- [API Mediation Layer configuration](#api-mediation-layer-configuration) +- [Cross memory server](#cross-memory-server) +- [Extensions](#extensions) -### Component prerequisites +### Zowe prerequisites - `JAVA_HOME`: The path where 64-bit Java 8 or later is installed. Only needs to be specified if not already set as a shell variable. Defaults to `/usr/lpp/java/J8.0_64`. - `NODE_HOME`: The path to the Node.js runtime. Only needs to be specified if not already set as a shell variable. -- `SKIP_NODE` : When Zowe starts, it checks whether the `NODE_HOME` path is a valid node runtime. If not, it will prompt for the location of where node can be located. Specify a value of `1` to bypass this step, or `0` for the check to occur. This may be useful in an automation scenario where the `zowe-start.sh` script is run unattended and the makeup of the components being launched does not require a node runtime. - `ROOT_DIR`: The directory where the Zowe runtime is located, also referred to as the ``. Defaults to the location of where `zowe-configure-instance` was executed. - `ZOSMF_PORT`: The port used by z/OSMF REST services. Defaults to value determined through running `netstat`. - `ZOSMF_HOST`: The host name of the z/OSMF REST API services. + +- `ZOWE_EXPLORER_HOST`: The hostname of where the Explorer servers are launched from. Defaults to running `hostname -c`. Ensure that this host name is externally accessible from clients who want to use Zowe as well as internally accessible from z/OS itself. +- `ZOWE_IP_ADDRESS`: The IP address of your z/OS system which must be externally accessible to clients who want to use Zowe. This is important to verify for IBM Z Development & Test Environment and cloud systems, where the default that is determined through running `ping` and `dig` on z/OS returns a different IP address from the external address. + +### Domain, Hostname and IP Address + - `ZOWE_EXPLORER_HOST`: The hostname of where the Explorer servers are launched from. Defaults to running `hostname -c`. Ensure that this host name is externally accessible from clients who want to use Zowe as well as internally accessible from z/OS itself. - `ZOWE_IP_ADDRESS`: The IP address of your z/OS system which must be externally accessible to clients who want to use Zowe. This is important to verify for IBM Z Development & Test Environment and cloud systems, where the default that is determined through running `ping` and `dig` on z/OS returns a different IP address from the external address. -- `APIML_ENABLE_SSO`: Define whether single sign-on should be enabled. Use a value of `true` or `false`. Defaults to `false`. + +When configuring a Zowe instance through the `instance.env` file, `ZOWE_IP_ADDRESS` and `ZOWE_EXPLORER_HOST` are used to specify where the Zowe servers can be reached. + +However, these values may not reflect the website name that you access Zowe from. This is especially true in the following cases: +- You are using a proxy +- The URL is a derivative of the value of `ZOWE_EXPLORER_HOST`, such as `myhost` versus `myhost.mycompany.com` + +In these cases, it may be necessary to specify a value for `ZWE_EXTERNAL_HOSTS` in the form of a comma-separated list of the addresses from which you want to access Zowe in your browser. + +In the previous example, `ZWE_EXTERNAL_HOSTS` could include both `myhost` and `myhost.mycompany.com`. In the `instance.env`, this would look like: `ZWE_EXTERNAL_HOSTS=myhost,myhost.mycompany.com` + +This configuration value maybe used for multiple purposes, including referrer-based security checks. In the case that the values are not specified, referrer checks will use the default values of `ZOWE_IP_ADDRESS`, `ZOWE_EXPLORER_HOST`, and the system's hostname. Therefore, if these values are not what you put into your browser, you will want to specify `ZWE_EXTERNAL_HOSTS` to set the correct value. + +- `ZOWE_EXPLORER_FRAME_ANCESTORS`: The MVS, USS, and JES Explorer are served by their respective explorer UI address spaces. These are accessed through the Zowe desktop where they are hosted as iFrames. To protect against double iFrame security vulnerabilities, browsers all of the valid address that may be used by the browser must be explicitly declared in this property. The default values are: `"${ZOWE_EXPLORER_HOST}:*,${ZOWE_IP_ADDRESS}:*"`. If there are any other URLs by which the Zowe Explorers can be served, then these should be appended to the preceding comma-separated list. + +### Component groups + +`LAUNCH_COMPONENT_GROUPS`: This is a comma-separated list of which z/OS microservice groups are started when Zowe launches. + - `GATEWAY` will start the API mediation layer that includes the API catalog, the API gateway, and the API discovery service. These three address spaces are Apache Tomcat servers and use the version of Java on z/OS as determined by the `JAVA_HOME` value. In addition to the mediation layer, the z/OS Explorer services are included here as well. + - `DESKTOP` will start the Zowe desktop that is the browser GUI for hosting Zowe applications such as the 3270 Terminal emulator or the File Explorer. It will also start ZSS. The Zowe desktop is a node application and uses the version specified by the `NODE_HOME` value. + - `ZSS` will start the ZSS server without including the Desktop and Application Framework server. This can be used with Docker so that you do not run servers on z/OS that will already be running within Docker. This may also be useful if you want to utilize ZSS core features or plug-ins without needing the Desktop. ZSS is a pre-requisite for the Zowe desktop, so when the `DESKTOP` group is specified then the zss server will be implicitly started. For more information on the zssServer and the technology stack of the Zowe servers see [Zowe architecture](../getting-started/zowe-architecture.md). + - Vendor products may extend Zowe with their own component group that they want to be lifecycled by the Zowe `ZWESVSTC` started task and run as a Zowe sub address space. To do this, specify the fully qualified directory provided by the vendor that contains their Zowe extension scripts. This directory will contain a `start.sh` script **(required)** that is called when the `ZWESVSTC` started task is launched, a `configure.sh` script **(optional)** that performs any configuration steps such as adding iFrame plug-ins to the Zowe desktop, and a `validate.sh` script **(optional)** that can be used to perform any pre-launch validation such as checking system prerequisites. For more information about how a vendor can extend Zowe with a sub address space, see the [Extending](../extend/extend-apiml/onboard-overview.md) section. + +**Note: If you are using Docker, it is recommended to remove GATEWAY and DESKTOP from LAUNCH_COMPONENT_GROUPS by setting `LAUNCH_COMPONENT_GROUPS=ZSS`. This will prevent duplication of servers running both in Docker and on z/OS.** ### Keystore configuration @@ -141,19 +181,31 @@ To determine which ports are not available, follow these steps: - `ZOWE_ZLUX_TELNET_PORT`: The Zowe desktop contains an application *3270 Terminal* which opens a 3270 emulator inside the Zowe desktop web page. This port is the number used by the z/OS telnet service and defaults to 23. The USS command `netstat -b | grep TN3270` can be used to display the telnet port used on a z/OS system. - `ZOWE_ZLUX_SECURITY_TYPE`: The *3270 Terminal* application needs to know whether the telnet service is using `tls` or `telnet` for security. The default value is blank for `telnet`. -### Gateway configuration +### API Mediation Layer configuration + +The following parameters can be set to customize the configuration of all API Mediation Layer components: + +- `APIML_DEBUG_MODE_ENABLED` : When this parameter is set to `true`, detailed logging of activity by the API mediation layer occurs. This can be useful to diagnose unexpected behavior of the API gateway, API discovery, or API catalog services. Default value is `false`. + +The following parameters can be set to customize the configuration of the Discovery: + +- `ZWE_DISCOVERY_SERVICES_LIST`: A comma-separated list of the endpoints for each Discovery Service instance. The default value is `https://${ZOWE_EXPLORER_HOST}:${DISCOVERY_PORT}/eureka/`. The following parameters can be set to customize the configuration of the Gateway: - `APIML_ALLOW_ENCODED_SLASHES`: When this parameter is set to `true`, the Gateway allows encoded characters to be part of URL requests redirected through the Gateway. - `APIML_CORS_ENABLED`: When this parameter is set to `true`, CORS are enabled in the API Gateway for Gateway routes `api/v1/gateway/**`. -- `APIML_PREFER_IP_ADDRESS`: Set this parameter to `true` to advertise a service IP address instead of its hostname. -- `APIML_GATEWAY_TIMEOUT_MILLIS`: Spcifies the timeout for connection to the services in milliseconds. +- `APIML_PREFER_IP_ADDRESS`: Set this parameter to `true` to advertise a service IP address instead of its hostname. **Note**, this configuration is deprecated. Zowe start script will ignore this value and always set it to `false`. +- `APIML_GATEWAY_TIMEOUT_MILLIS`: Specifies the timeout for connection to the services in milliseconds. - `APIML_SECURITY_X509_ENABLED`: Set this parameter to `true`, to enable the client certificate authentication functionality through ZSS. - `APIML_SECURITY_ZOSMF_APPLID`: The z/OSMF APPLID used for PassTicket. - `APIML_SECURITY_AUTH_PROVIDER`: The authentication provider used by the API Gateway. By default, the API Gateway uses z/OSMF as an authentication provider. It is possible to switch to SAF as the authentication provider instead of z/OSMF. -- `APIML_DEBUG_MODE_ENABLED` : When this parameter is set to `true`, detailed logging of activity by the API mediation layer occurs. This can be useful to diagnose unexpected behavior of the API gateway, API discovery, or API catalog services. Default value is `false`. +The following values are used to customize the configuration of Caching Service. + +- `ZWE_CACHING_SERVICE_PORT=7555`: The port the Caching Service will use. +- `ZWE_CACHING_SERVICE_PERSISTENT=`: This field sets the storage type used to persist data in the Caching Service. Valid options are `REDIS` or `VSAM`. `REDIS` is currently only supported as an off-Z storage solution. `VSAM` is only supported on Z. +- `ZWE_CACHING_SERVICE_VSAM_DATASET`: This field sets the `VSAM` dataset name to be used to store Caching Service data. This field is required if `ZWE_CACHING_SERVICE_PERSISTENT` is set to `VSAM`, otherwise this field is not needed. Refer to detailed section about [API Gateway configuration](api-mediation/api-gateway-configuration.md) @@ -171,30 +223,373 @@ Refer to detailed section about [API Gateway configuration](api-mediation/api-ga - `EXTERNAL_COMPONENTS`: For third-party extenders to add the full path to the directory that contains their component lifecycle scripts. For more information, see [Zowe lifecycle - Zowe extensions](../extend/lifecycling-with-zwesvstc.md#zowe-extensions). -### High Availability -The high availability (HA) feature of Zowe is under development and has not been fully delivered. The following values are work in progress towards HA capability. They are not used and will be documented in more detail once HA support is finalized in a future Zowe release. +## Updating the zowe.yaml configuration file (Technical Preview) -- `ZWE_DISCOVERY_SERVICES_LIST`: _(Work in progress)_ **Do not modify this value** from its supplied default of `https://${ZOWE_EXPLORER_HOST}:${DISCOVERY_PORT}/eureka/`. -- `ZWE_CACHING_SERVICE_PORT=7555`: _(Work in progress)_ This port is not yet used so the value does not need to be availale. -- `ZWE_CACHING_SERVICE_PERSISTENT=VSAM`: _(Work in progress)_ -- `ZWE_CACHING_SERVICE_VSAM_DATASET`: _(Work in progress)_ + -## Configuring a Zowe instance via `instance.env` file +_Note: This feature is added with Zowe v1.22.0 release for technical preview and we are happy to hear any feedback. Content in this section may be changed or improved in the future._ -When configuring a Zowe instance through the `instance.env` file, `ZOWE_IP_ADDRESS` and `ZOWE_EXPLORER_HOST` are used to specify where the Zowe servers can be reached. +Instead of using `instance.env` to configure the Zowe runtime, you can also use a `zowe.yaml` file to configure Zowe in more granular level. `zowe.yaml` is also required to start Zowe in high availability mode. To make Zowe runtime recognize the `zowe.yaml` configuration, you must create a `zowe.yaml` file and remove the `instance.env` file from the instance directory. See [Creating the zowe.yaml file](#creating-the-zoweyaml-file) for instructions. -However, these values may not reflect the website name that you access Zowe from. This is especially true in the following cases: -- You are using a proxy -- The URL is a derivative of the value of `ZOWE_EXPLORER_HOST`, such as `myhost` versus `myhost.mycompany.com` +**Note:** In the following sections, we refer configuration keys with concatenation of key names and dots. For example, if you want to update the configuration key `zowe.internalCertificate.keystore.type` with value `PKCS12`, you should set value for this entry in the `zowe.yaml`: -In these cases, it may be necessary to specify a value for `ZWE_EXTERNAL_HOSTS` in the form of a comma-separated list of the addresses from which you want to access Zowe in your browser. +```yaml +zowe: + internalCertificate: + keystore: + type: PKCS12 +``` -In the previous example, `ZWE_EXTERNAL_HOSTS` could include both `myhost` and `myhost.mycompany.com`. In the `instance.env`, this would look like: `ZWE_EXTERNAL_HOSTS=myhost,myhost.mycompany.com` +To learn more about the YAML format, please visit [yaml.org](https://yaml.org/). + +**Contents in this section** + +- [Known limitations for Zowe high availability](#known-limitations-for-zowe-high-availability) +- [Creating the zowe.yaml file](#creating-the-zoweyaml-file) +- [High level overview of YAML configuration file](#high-level-overview-of-yaml-configuration-file) +- [Extract sharable configuration out of zowe.yaml](#extract-sharable-configuration-out-of-zoweyaml) +- [Configuration override](#configuration-override) +- [YAML configurations - certificate](#yaml-configurations---certificate) +- [YAML configurations - zowe](#yaml-configurations---zowe) +- [YAML configurations - java](#yaml-configurations---java) +- [YAML configurations - node](#yaml-configurations---node) +- [YAML configurations - zOSMF](#yaml-configurations---zosmf) +- [YAML configurations - components](#yaml-configurations---components) + - [Configure component gateway](#configure-component-gateway) + - [Configure component discovery](#configure-component-discovery) + - [Configure component api-catalog](#configure-component-api-catalog) + - [Configure component caching-service](#configure-component-caching-service) + - [Configure component app-server](#configure-component-app-server) + - [Configure component zss](#configure-component-zss) + - [Configure component jobs-api](#configure-component-jobs-api) + - [Configure component files-api](#configure-component-files-api) + - [Configure component explorer-jes](#configure-component-explorer-jes) + - [Configure component explorer-mvs](#configure-component-explorer-mvs) + - [Configure component explorer-uss](#configure-component-explorer-uss) + - [Configure external extension](#configure-external-extension) +- [YAML configurations - haInstances](#yaml-configurations---hainstances) + +### Known limitations for Zowe high availability + +- To allow Sysplex Distributor to route traffic to Gateway, you can only start one Gateway in each LPAR within the Sysplex. All Gateways instances should be started on the same port configured on Sysplex Distributor. +- Zowe App Server should be accessed through Gateway with URL like `https://:/zlux/ui/v1`. +- Currently, the `app-server` component can only be configured to start one instance. +- If you enabled more than one Discovery service, you may see a 500 error if you click on the `Refresh Static APIs` button from API Catalog. + +### Creating the zowe.yaml file + +There are two ways to create a `zowe.yaml` file. + +- Copy the example file `/bin/example-zowe.yaml` to `/zowe.yaml` and modify it based on your configuration. +- Convert from an existing `instance.env` file by using a utility tool in `/bin/utils/convert-to-zowe-yaml.sh` shipped with Zowe. Issue the following command to convert an `instance.env` file to `zowe.yaml` format: -This configuration value maybe used for multiple purposes, including referrer-based security checks. In the case that the values are not specified, referrer checks will use the default values of `ZOWE_IP_ADDRESS`, `ZOWE_EXPLORER_HOST`, and the system's hostname. Therefore, if these values are not what you put into your browser, you will want to specify `ZWE_EXTERNAL_HOSTS` to set the correct value. + ``` + /bin/utils/convert-to-zowe-yaml.sh /instance.env /zowe.yaml + ``` + + where, the `` is your instance directory path. + +After `zowe.yaml` is created, you should add new `haInstances` section and define ha-instance(s) you want to start in your Sysplex. + +### High level overview of YAML configuration file + +The YAML configuration file has few high level sections: + +- **`zowe`**: defines global configurations specific to Zowe, including default values. +- **`java`**: defines Java configurations used by Zowe components. +- **`node`**: defines node.js configurations used by Zowe components. +- **`zOSMF`**: tells Zowe your z/OSMF configurations. +- **`components`**: defines detailed configurations for each Zowe component or extension. Each component or extension may have a key entry under this section. For example, `components.gateway` is configuration for API Mediation Layer Gateway service. +- **`haInstances`**: defines customized configurations for each High Availability (HA) instance. You should predefine all Zowe HA instances you want to start within your Sysplex. + +### Extract sharable configuration out of zowe.yaml + +The Zowe YAML configuration file supports a special `@include` annotation that can be used in any level of the configuration. This enables you to organize your YAML configuration files and extract sharable configurations to a separate YAML file. + +For example, you can define a sharable certificate configuration file `/zowe-certificates.yaml` like this: + +```yaml +keystore: + alias: localhost + password: password + file: /global/zowe/keystore/localhost/localhost.keystore.p12 + type: PKCS12 +trustStore: + file: /global/zowe/keystore/localhost/localhost.truststore.p12 + certificateAuthorities: "" +pem: + key: /global/zowe/keystore/localhost/localhost.keystore.key + certificate: /global/zowe/keystore/localhost/localhost.keystore.cer-ebcdic + certificateAuthority: /global/zowe/keystore/local_ca/localca.cer-ebcdic +``` + +Then in your `/zowe.yaml`, you can import this certification file like this: + +```yaml +zowe: + externalCertificate: + @include: "/zowe-certificates.yaml" + internalCertificate: + @include: "/zowe-certificates.yaml" +``` + +### Configuration override + +Inside `zowe.yaml`, you can define default values and they may be overridden in more granular level configurations. This can happen in several ways: + +- Component can override default certificate configuration. For specific entry of certification configuration, if it's not overridden, it will fall back to default configurations. For example, in this configuration: + + ```yaml + zowe: + internalCertificate: + keystore: + alias: localhost + password: password + file: /global/zowe/keystore/localhost/localhost.keystore.p12 + type: PKCS12 + trustStore: + file: /global/zowe/keystore/localhost/localhost.truststore.p12 + certificateAuthorities: "" + pem: + key: /global/zowe/keystore/localhost/localhost.keystore.key + certificate: /global/zowe/keystore/localhost/localhost.keystore.cer-ebcdic + certificateAuthority: /global/zowe/keystore/local_ca/localca.cer-ebcdic + components: + app-server: + certificate: + keystore: + alias: app-server + pem: + key: /global/zowe/keystore/localhost/localhost.keystore.app-server.key + certificate: /global/zowe/keystore/localhost/localhost.keystore.app-server.cer-ebcdic + ``` + + App Server will use the certificate alias `app-server` instead of `localhost` from the same keystore defined in `zowe.internalCertificate.keystore.file`. And it will use the exact same truststore defined in `zowe.internalCertificate.trustStore.file`. + +- HA instance component configuration `haInstances..components.` can override global level component configurations `components.`. Any configuration you can find in `components.` level can be overridden in `haInstances..components.` level. For example, in this configuration: + + ```yaml + components: + app-server: + enabled: true + port: 8544 + haInstances: + lpar2a: + components: + app-server: + enabled: false + lpar2b: + components: + app-server: + port: 28544 + ``` + + App Server on `lpar2a` HA instance will not be started. On `lpar2b` HA instance, it will be started but on port 28544. + +### YAML configurations - certificate + +In Zowe YAML configuration, certificate definition shares the same format and this format can be used in several configuration entries. For example, `zowe.externalCertificate`, `zowe.internalCertificate`, `components..certificate`, and `haInstances..components..certificate`. The certificate definition may include the following entries: + +- `keystore.type`: Defines the type of the keystore. If you are using keystore, this value usually should be `PKCS12`. If you are using keyring, this value should be `JCERACFKS`. +- `keystore.file`: Defines the path of the keystore file. If you are using keyring, this should look like `safkeyring://///`. For example, `safkeyring:////ZWESVUSR/ZoweKeyring`. +- `keystore.alias`: represents the alias name of the certificate stored in keystore. If you are using keyring, this is the certificate label connected to the keyring. +- `keystore.password`: Defines the password of the keystore. +- `trustStore.file`: Defines the path to the truststore file. If you are using keyring, this should look like `safkeyring://///`, usually will be the same value of `keystore.file`. +- `trustStore.certificateAuthorities`: defines extra certificate authorities you will trust. This should point to CA files in PEM format. +- `pem.key`: Defines the private key file in PEM format. This can be used by applications that do not support either PKCS12 keystore format or z/OS keyring. +- `pem.certificate`: Defines the public key file in PEM format. This can be used by applications that do not support either PKCS12 keystore format or z/OS keyring. +- `pem.certificateAuthority`: Defines certificate authorities in PEM format. This can be used by applications that do not support either PKCS12 keystore format or z/OS keyring. + +**Note:** With the `zowe.yaml` configuration, all certificate related configurations are merged into the `zowe.yaml` file. `/zowe-certificates.env` will not be used. + +### YAML configurations - zowe + +The high-level configuration `zowe` supports these definitions: + +- `zowe.runtimeDirectory`: Tells Zowe the runtime directory connected to this Zowe instance. This is equivalent to the `ROOT_DIR` variable in the `instance.env` file. +- `zowe.extensionDirectory`: Tells Zowe where you put the runtime of all your extensions. This is equivalent to the `ZWE_EXTENSION_DIR` variable in the `instance.env` file. +- `zowe.jobPrefix`: Defines the Zowe job prefix for the ZWESVSTC started task. This is equivalent to the `ZOWE_PREFIX` variable in the `instance.env` file. +- `zowe.identifier`: Defines the Zowe job identifier for the ZWESVSTC started task. This is equivalent to the `ZOWE_INSTANCE` variable in the `instance.env` file. +- `zowe.externalDomains`: Defines a list of external domains that will be used by the Zowe instance. This configuration is an array of domain name strings. This is equivalent to the `ZWE_EXTERNAL_HOSTS` variable in the `instance.env` file but should be represented as an array. In Sysplex deployment, this is the DVIPA domain name defined in Sysplex Distributor. For example, + + ```yaml + zowe: + externalDomains: + - external.my-company.com + - additional-dvipa-domain.my-company.com + ``` + +- `zowe.externalPort`: Defines the port that will be exposed to external Zowe users. By default, this value is set based on the `GATEWAY_PORT` variable in the in the `instance.env` file. In Sysplex deployment, this is the DVIPA port defined in Sysplex Distributor. See [Configure Sysplex Distributor](configure-sysplex.md#configure-sysplex-distributor) for more information. +- `zowe.environments`: Defines extra environment variables to customize the Zowe runtime. This configuration is a list of key / value pairs. This is equivalent to adding new environment variables to the `instance.env` file. For example, + ```yaml + zowe: + environments: + MY_NEW_ENV: value-of-my-env + ``` +- `zowe.externalCertificate`: Defines the [northbound certificate](configure-certificates.md#northbound-certificate) facing Zowe users. These configurations are defined in `/zowe-certificates.env`. + + **Note:** This configuration is not the same as the `EXTERNAL_CERTIFICATE` configuration in `zowe-setup-certificates.env`. In `zowe-setup-certificates.env`, `EXTERNAL_CERTIFICATE` means that the certificate is not generated by the `zowe-setup-certificates.sh` utility script. + +- `zowe.internalCertificate`: Defines the default [southbound certificate](configure-certificates.md#southbound-certificate) used within Zowe services. These configurations are defined in `/zowe-certificates.env`. By default, this is the same as `zowe.externalCertificate`. +- `zowe.sso.token.name`: Defines SSO token name. This is equivalent to the `PKCS11_TOKEN_NAME` variable in `/zowe-certificates.env`. +- `zowe.sso.token.label`: Defines the certificate label that binds to SSO token. This is equivalent to the `PKCS11_TOKEN_LABEL` variable in `/zowe-certificates.env`. + +### YAML configurations - java + +The high-level configuration `java` supports these definitions: + +- `home`: Defines the path to the Java runtime directory. This is equivalent to the `JAVA_HOME` variable in the `instance.env` file. + +### YAML configurations - node + +The high-level configuration `node` supports these definitions: + +- `home`: Defines the path to the Node.js runtime directory. This is equivalent to the `NODE_HOME` variable in the `instance.env` file. + +### YAML configurations - zOSMF + +The high-level configuration `zOSMF` supports these definitions: + +- `zOSMF.host`: Defines the hostname of your z/OSMF instance. This is equivalent to the `ZOSMF_HOST` variable in the `instance.env` file. +- `zOSMF.port`: Defines the port of your z/OSMF instance. This is equivalent to the `ZOSMF_PORT` variable in the `instance.env` file. +- `zOSMF.applId`: Defines the application ID of your z/OSMF instance. This is equivalent to the `APIML_SECURITY_ZOSMF_APPLID` variable in the `instance.env` file. + +### YAML configurations - components + +All Zowe components and extensions can have a dedicated section under the `components` high-level configuration. + +In this section, `` represents any Zowe components or extensions. For all components and extensions, these are the common definitions. + +- `components..enabled`: Defines if you want to start this component in this Zowe instance. This is a much detailed granular definition of the `LAUNCH_COMPONENT_GROUPS` variable in `instance.env`. This allows you to control each component instead of a group. For external components, also known as extensions, this configuration also replaces the `EXTERNAL_COMPONENTS` variable in `instance.env`. +- `components..certificate`: you can customize a component to use different certificate from default values. This section follows same format defined in [YAML configurations - certificate](#yaml-configurations-certificate). If this is not customized, the component will use certificates defined in `zowe.internalCertificate`. + +#### Configure component gateway + +These configurations can be used under the `components.gateway` section: + +- `port`: Defines the port which the gateway should be started on. This is equivalent to the `GATEWAY_PORT` variable in `instance.env`. +- `debug`: Defines whether to enable debug mode for gateway. This is equivalent to the `APIML_DEBUG_MODE_ENABLED` variable in `instance.env` but with better granular level. +- `apiml.service.allowEncodedSlashes`: When this parameter is set to `true`, the Gateway allows encoded characters to be part of URL requests redirected through the Gateway. This is equivalent to the `APIML_ALLOW_ENCODED_SLASHES` variable in `instance.env`. +- `apiml.service.corsEnabled`: When this parameter is set to `true`, CORS are enabled in the API Gateway for Gateway routes `api/v1/gateway/**`. This is equivalent to the `APIML_CORS_ENABLED` variable in `instance.env`. +- `apiml.service.preferIpAddress`: Set this parameter to `true` to advertise a service IP address instead of its hostname. **Note:** This configuration is deprecated. Zowe start script will ignore this value and always set it to `false`. This is equivalent to the `APIML_PREFER_IP_ADDRESS` variable in `instance.env`. +- `apiml.gateway.timeoutMillis`: Specifies the timeout for connection to the services in milliseconds. This is equivalent to the `APIML_GATEWAY_TIMEOUT_MILLIS` variable in `instance.env`. +- `apiml.security.x509.enabled`: Set this parameter to `true` to enable the client certificate authentication functionality through ZSS. This is equivalent to the `APIML_SECURITY_X509_ENABLED` variable in `instance.env`. +- `apiml.security.x509.externalMapperUrl`: Defines the URL where Gateway can query the mapping of client certificates. This is equivalent to the `APIML_GATEWAY_EXTERNAL_MAPPER` variable in `instance.env`. +- `apiml.security.zosmf.applid`: Defines the z/OSMF APPLID used for PassTicket. This is equivalent to the `APIML_SECURITY_ZOSMF_APPLID` variable in `instance.env`. This should have the same value of `zOSMF.applId`. This entry is kept for backward compatibility. +- `apiml.security.auth.provider`: Defines the authentication provider used by the API Gateway. This is equivalent to the `APIML_SECURITY_AUTH_PROVIDER` variable in `instance.env`. +- `apiml.security.authorization.endpoint.url`: Defines the URL to the authorization endpoint. This endpoint tells Gateway if a user has a particular permission on SAF profile. For example, permission to the `APIML.SERVICES` profile of `ZOWE` class. This is equivalent to the `APIML_SECURITY_AUTHORIZATION_ENDPOINT_URL` variable in `instance.env`. +- `apiml.security.ssl.verifySslCertificatesOfServices`: Defines whether APIML should verify certificates of services in strict mode. Setting to `true` will enable the `strict` mode where APIML will validate if the certificate is trusted in turststore, and also if the certificate Common Name or Subject Alternate Name (SAN) matches the service hostname. This is equivalent to the `VERIFY_CERTIFICATES` variable defined in `/zowe-certificates.env`. +- `apiml.security.ssl.nonStrictVerifySslCertificatesOfServices`: Defines whether APIML should verify certificates of services in non-strict mode. Setting the value to `true` will enable the `non-strict` mode where APIML will validate if the certificate is trusted in turststore, but ignore the certificate Common Name or Subject Alternate Name (SAN) check. Zowe will ignore this configuration when strict mode is enabled with `apiml.security.ssl.verifySslCertificatesOfServices`. This is equivalent to the `NONSTRICT_VERIFY_CERTIFICATES` variable defined in `/zowe-certificates.env`. +- `apiml.server.maxConnectionsPerRoute`: Specifies the maximum connections for each service. This is equivalent to the `APIML_MAX_CONNECTIONS_PER_ROUTE` variable in `instance.env`. +- `apiml.server.maxTotalConnections`: Specifies the total connections for all services registered under API Mediation Layer. This is equivalent to the `APIML_MAX_TOTAL_CONNECTIONS` variable in `instance.env`. + +#### Configure component discovery + +These configurations can be used under the `components.discovery` section: + +- `port`: Defines the port which discovery should be started on. This is equivalent to the `DISCOVERY_PORT` variable in `instance.env`. +- `debug`: Defines whether to enable debug mode for gateway. This is equivalent to the `APIML_DEBUG_MODE_ENABLED` variable in `instance.env` but with better granular level. +- `apiml.service.preferIpAddress`: Set this parameter to `true` to advertise a service IP address instead of its hostname. **Note:** This configuration is deprecated. The Zowe start script will ignore this value and always set it to `false`. This is equivalent to the `APIML_PREFER_IP_ADDRESS` variable in `instance.env`. +- `apiml.security.ssl.verifySslCertificatesOfServices`: Defines whether APIML should verify certificates of services in strict mode. Setting to `true` will enable the `strict` mode where APIML will validate both if the certificate is trusted in turststore, and also if the certificate Common Name or Subject Alternate Name (SAN) matches the service hostname. This is equivalent to the `VERIFY_CERTIFICATES` variable defined in `/zowe-certificates.env`. +- `apiml.security.ssl.nonStrictVerifySslCertificatesOfServices`: Defines whether APIML should verify certificates of services in non-strict mode. Setting to `true` will enable the `non-strict` mode where APIML will validate if the certificate is trusted in turststore, but ignore the certificate Common Name or Subject Alternate Name (SAN) check. Zowe will ignore this configuration if strict mode is enabled with `apiml.security.ssl.verifySslCertificatesOfServices`. This is equivalent to the `NONSTRICT_VERIFY_CERTIFICATES` variable defined in `/zowe-certificates.env`. +- `alternativeStaticApiDefinitionsDirectories`: Specifies the alternative directories of static definitions. This is equivalent to the `APIML_MAX_CONNECTIONS_PER_ROUTE` variable in `instance.env`. +- `apiml.server.maxTotalConnections`: Specifies the total connections for all services registered under API Mediation Layer. This is equivalent to the `ZWEAD_EXTERNAL_STATIC_DEF_DIRECTORIES` variable in `instance.env`. + +#### Configure component api-catalog + +These configurations can be used under the `components.api-catalog` section: + +- `port`: Defines the port which API Catalog should be started on. This is equivalent to the `CATALOG_PORT` variable in `instance.env`. +- `debug`: Defines if we want to enable debug mode for gateway. This is equivalent to the `APIML_DEBUG_MODE_ENABLED` variable but with better granular level. +- `environment.preferIpAddress`: Set this parameter to `true` to advertise a service IP address instead of its hostname. **Note:** This configuration is deprecated. Zowe start script will ignore this value and always set it to `false`. This is equivalent to the `APIML_PREFER_IP_ADDRESS` variable in `instance.env`. + +#### Configure component caching-service + +These configurations can be used under the `components.caching-service` section: + +- `port`: Defines the port which Caching Service should be started on. This is equivalent to the `ZWE_CACHING_SERVICE_PORT` variable in `instance.env`. +- `debug`: Defines if we want to enable debug mode for gateway. This is equivalent to the `APIML_DEBUG_MODE_ENABLED` variable in `instance.env` but with better granular level. +- `storage.mode`: Sets the storage type used to persist data in the Caching Service. This is equivalent to the `ZWE_CACHING_SERVICE_PERSISTENT` variable in `instance.env`. +- `storage.size`: Specifies amount of records before eviction strategies start evicting. This is equivalent to the `ZWE_CACHING_STORAGE_SIZE` variable in `instance.env`. +- `storage.evictionStrategy`: Specifies eviction strategy to be used when the storage size is achieved. This is equivalent to the `ZWE_CACHING_EVICTION_STRATEGY` variable in `instance.env`. +- `storage.vsam.name`: Specifies the data set name of the caching service VSAM data set. This is equivalent to the `ZWE_CACHING_SERVICE_VSAM_DATASET` variable in `instance.env`. +- `environment.preferIpAddress`: Set this parameter to `true` to advertise a service IP address instead of its hostname. **Note:** this configuration is deprecated. Zowe start script will ignore this value and always set it to `false`. This is equivalent to the `APIML_PREFER_IP_ADDRESS` variable in `instance.env`. +- `apiml.security.ssl.verifySslCertificatesOfServices`: Specifies whether APIML should verify certificates of services in strict mode. Set to `true` will enable `strict` mode that APIML will validate both if the certificate is trusted in turststore, and also if the certificate Common Name or Subject Alternate Name (SAN) match the service hostname. This is equivalent to the `VERIFY_CERTIFICATES` variable defined in `/zowe-certificates.env`. +- `apiml.security.ssl.nonStrictVerifySslCertificatesOfServices`: Defines whether APIML should verify certificates of services in non-strict mode. Setting to `true` will enable `non-strict` mode where APIML will validate if the certificate is trusted in turststore, but ignore the certificate Common Name or Subject Alternate Name (SAN) check. Zowe will ignore this configuration if strict mode is enabled with `apiml.security.ssl.verifySslCertificatesOfServices`. This is equivalent to the `NONSTRICT_VERIFY_CERTIFICATES` variable defined in `/zowe-certificates.env`. + +#### Configure component app-server + +These configurations can be used under the `components.app-server` section: + +- `port`: Defines the port which App Server should be started on. This is equivalent to the `ZOWE_ZLUX_SERVER_HTTPS_PORT` variable in `instance.env`. + +#### Configure component zss + +These configurations can be used under the `components.zss` section: + +- `port`: Defines the port which ZSS should be started on. This is equivalent to the `ZOWE_ZSS_SERVER_PORT` variable in `instance.env`. +- `crossMemoryServerName`: Defines the procedure name of cross memory server. This is equivalent to the `ZOWE_ZSS_XMEM_SERVER_NAME` variable in `instance.env`. +- `tls`: Defines whether ZSS service has enabled TLS. This is equivalent to the `ZOWE_ZSS_SERVER_TLS` variable in `instance.env`. + +#### Configure component jobs-api + +These configurations can be used under the `components.jobs-api` section: + +- `port`: Defines the port which Jobs API should be started on. This is equivalent to the `JOBS_API_PORT` variable in `instance.env`. + +#### Configure component files-api + +These configurations can be used under the `components.files-api` section: + +- `port`: Defines the port which Files API should be started on. This is equivalent to the `FILES_API_PORT` variable in `instance.env`. + +#### Configure component explorer-jes + +These configurations can be used under the `components.explorer-jes` section: + +- `port`: Defines the port which JES UI Explorer should be started on. This is equivalent to the `JES_EXPLORER_UI_PORT` variable in `instance.env`. +- `frameAncestors`: Defines the frame ancestors supported by UI Explorer. This is equivalent to the `ZOWE_EXPLORER_FRAME_ANCESTORS` variable in `instance.env` but in better granular level. + +#### Configure component explorer-mvs + +These configurations can be used under the `components.explorer-mvs` section: + +- `port`: Defines the port which MVS UI Explorer should be started on. This is equivalent to the `MVS_EXPLORER_UI_PORT` variable in `instance.env`. +- `frameAncestors`: Defines the frame ancestors supported by UI Explorer. This is equivalent to the `ZOWE_EXPLORER_FRAME_ANCESTORS` variable in `instance.env` but in better granular level. + +#### Configure component explorer-uss + +These configurations can be used under the `components.explorer-uss` section: + +- `port`: Defines the port which USS UI Explorer should be started on. This is equivalent to the `USS_EXPLORER_UI_PORT` variable in `instance.env`. +- `frameAncestors`: Defines the frame ancestors supported by UI Explorer. This is equivalent to the `ZOWE_EXPLORER_FRAME_ANCESTORS` variable in `instance.env` but in better granular level. + +#### Configure external extension + +You can define a `components.` section and use common component configuration entries. + +For example, enable `my-extension`: + +```yaml +components: + # for extensions, you can add your definition like this + my-extension: + enabled: true +``` + +### YAML configurations - haInstances + +All Zowe high availability instances should have a dedicated section under the `haInstances` high-level configuration. + +In this section, `` represents any Zowe high availability instance ID. + +For all high availability instances, these are the common definitions. + +- `haInstances..hostname`: Defines the host name where you want to start this instance. This could be the host name of one LPAR in your Sysplex. +- `haInstances..ip`: Defines the IP address where you want to start this instance. This could be the IP address of one LPAR in your Sysplex. +- `haInstances..components.`: Optional settings you can override component configurations for this high availability instance. See [Configuration override](#configuration-override) for more details. -- `ZOWE_EXPLORER_FRAME_ANCESTORS`: The MVS, USS, and JES Explorer are served by their respective explorer UI address spaces. These are accessed through the Zowe desktop where they are hosted as iFrames. To protect against double iFrame security vulnerabilities, browsers all of the valid address that may be used by the browser must be explicitly declared in this property. The default values are: `"${ZOWE_EXPLORER_HOST}:*,${ZOWE_IP_ADDRESS}:*"`. If there are any other URLs by which the Zowe Explorers can be served, then these should be appended to the preceding comma-separated list. ## Hints and tips @@ -202,7 +597,7 @@ Learn about some hints and tips that you might find useful when you create and c When you are configuring Zowe on z/OS, you need to [create certificates](configure-certificates.md), and then create the Zowe instance. -The creation of a Zowe instance is controlled by the [`instance.env` file](#reviewing-the-instanceenv-file) in your instance directory `INSTANCE_DIR`. +The creation of a Zowe instance is controlled by the [`instance.env` file](#updating-the-instance-env-configuration-file) in your instance directory `INSTANCE_DIR`. 1. Keystore diff --git a/docs/user-guide/configure-sysplex.md b/docs/user-guide/configure-sysplex.md new file mode 100644 index 0000000000..70d711d1c4 --- /dev/null +++ b/docs/user-guide/configure-sysplex.md @@ -0,0 +1,64 @@ +# Configuring Sysplex for high availability + +To deploy Zowe high availability, you must set up the Parallel Sysplex® environment. A Parallel Sysplex is a collection of z/OS® systems that cooperatively use certain hardware and software components to achieve a high-availability workload processing environment. + +## Sysplex environment requirements + +Zowe high availability instances require a Sysplex environment that consists of the following: + +- One or more central processor complexes (CPCs) that can attach to a coupling facility +- At least one coupling facility +- At least one Sysplex timer +- Connection to shared DASD +- Shared SAF database, see [Sharing a database with sysplex communication in data sharing mode](https://www.ibm.com/docs/en/zos/2.1.0?topic=sd-sharing-database-sysplex-communication-in-data-sharing-mode) +- Sysplex Distributor with configured Dynamic VIPA TCP/IP address, see [Configuring Sysplex Distributor](#configuring-sysplex-distributor) for instructions +- VSAM record-level sharing (RLS), see [Preparing for VSAM record-level sharing](https://www.ibm.com/docs/en/zos/2.4.0?topic=sharing-preparing-vsam-record-level) +- USS Shared file system, see [How to share file systems in a Sysplex](https://www.ibm.com/docs/en/zos/2.4.0?topic=planning-sharing-file-systems-in-sysplex) +- JESPlex/JES2 Multi-Access Spool (MAS) environment +- z/OSMF high availability, see [Configuring z/OSMF high availability in Sysplex](systemrequirements-zosmf-ha.md) +- Node.js v8.x (except v8.16.1), v12.x, or v14 + + **Note:** It is highly recommended that Node.js installed on a shared file system. + +## Configuring Sysplex Distributor + +The following example DVIPA configuration ensures the availability of Zowe in Hot-Standby mode. For example, suppose that you have a Sysplex of two z/OS systems: A, B. + +1. Enable dynamic XCF on each host by adding the following TCP/IP definitions: + - `IPCONFIG SYSPLEXROUTING DYNAMICXCF x.x.x.A 255.255.255.0 1` for SYSA + - `IPCONFIG SYSPLEXROUTING DYNAMICXCF x.x.x.B 255.255.255.0 1` for SYSB + +2. Define a DVIPA for both systems: + + ``` + VIPADYNAMIC + VIPADEFINE 255.255.255.0 x.x.x.V + VIPADISTRIBUTE DEFINE DISTM HOTSTANDBY x.x.x.V + PORT 7554 DESTIP + x.x.x.A PREFERRED + x.x.x.B BACKUP + ENDVIPADYNAMIC + ``` + + where, + - x.x.x.A is the home address for SYSA. + - x.x.x.B is the home address for SYSB. + - x.x.x.V is Dynamic VIP Address. + - 7554 is the port number of you Zowe API Mediation Layer Gateway. This should be the same port number you configured for `zowe.externalPort` in `zowe.yaml`. See [Updating the zowe.yaml configuration file](configure-instance-directory.md#updating-the-zowe-yaml-configuration-file-technical-preview) to learn more about `zowe.yaml`. + +The `VIPADISTRIBUTE` statement with `PREFERRED` and `BACKUP` settings is used to enable automatic dynamic VIPA takeover to occur, if needed. + +All Zowe instances are bound to the DVIPA x.x.x.V. With both z/OS systems active in the Sysplex, the preferred Zowe instance, SYSA receives all new incoming requests. +If SYSA fails, new work requests to Zowe are routed to the server on SYSB. When SYSA resumes normal operations, new work requests for Zowe are routed to SYSA again. This is the default behavior because the `AUTOSWITCHBACK` parameter of the `VIPADISTRIBUTE` statement is in effect by default. + +If you do not want the distributor to switch back to the preferred target when it becomes available, you can specify the `NOAUTOSWITCHBACK` parameter for the `VIPADISTRIBUTE` statement. + +``` +VIPADYNAMIC + VIPADEFINE 255.255.255.0 x.x.x.V + VIPADISTRIBUTE DEFINE DISTM HOTSTANDBY NOAUTOSWITCHBACK x.x.x.V + PORT 7554 DESTIP + x.x.x.A PREFERRED + x.x.x.B BACKUP +ENDVIPADYNAMIC +``` diff --git a/docs/user-guide/configure-zos-system.md b/docs/user-guide/configure-zos-system.md index ee22afaf3a..ffd5e94693 100644 --- a/docs/user-guide/configure-zos-system.md +++ b/docs/user-guide/configure-zos-system.md @@ -27,6 +27,7 @@ When you run the `ZWESECUR` JCL, it does not perform the following initializatio The `ZWESECUR` JCL performs the following initialization steps so you do not need to perform them manually if you have successfully run the JCL. These steps are included for reference if you prefer to manually configure the z/OS environment or want to learn more about user IDs, groups, and associated security permissions that are required to operate Zowe. - [User IDs and groups for the Zowe started tasks](#user-ids-and-groups-for-the-zowe-started-tasks) - [Configure ZWESVSTC to run under ZWESVUSR user ID](#configure-zwesvstc-to-run-under-zwesvusr-user-ID) +- [Configure ZWESLSTC to run high availability instances under ZWESVUSR user ID](#configure-zweslstc-to-run-under-zwesvusr-user-ID) - [Configure the cross memory server for SAF](#configure-the-cross-memory-server-for-saf) @@ -64,9 +65,11 @@ The zssServer uses cookies that require random number generation for security. T If you have not configured your z/OS environment for ICSF, see [Cryptographic Services ICSF: System Programmer's Guide](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.csfb200/abstract.htm) for more information. To see whether ICSF has been started, check whether the started task `ICSF` or `CSF` is active. +If you run Zowe high availability on a Sysplex, ICSF needs to be configured in a Sysplex environment to share KDS data sets across systems in a Sysplex. For detailed information, see [Running in a Sysplex Environment](https://www.ibm.com/docs/en/zos/2.3.0?topic=guide-running-in-sysplex-environment) + The Zowe z/OS environment configuration JCL member `ZWESECUR` does not perform any steps related to ICSF that is required for zssServer that the Zowe desktop uses. Therefore, if you want to use Zowe desktop, you must perform the steps that are described in this section manually. -To generate symmetric keys, the `ZWESVUSR` user who runs `ZWESVSTC` requires READ access to `CSFRNGL` in the `CSFSERV` class. +To generate symmetric keys, the `ZWESVUSR` user who runs Zowe server started task requires READ access to `CSFRNGL` in the `CSFSERV` class. Define or check the following configurations depending on whether ICSF is already installed: @@ -140,11 +143,11 @@ Define or check the following configurations depending on whether ICSF is alread ## Configure security environment switching -Typically, the user `ZWESVUSR` that the `ZWESVSTC` started task runs under needs to be able to change the security environment of its process to allow API requests to be issued on behalf of the logged on TSO user ID, rather than the server's user ID. This capability provides the functionality that allows users to log on to the Zowe desktop and use apps such as the File Editor to list data sets or USS files that the logged on user is authorized to view and edit, rather than the user ID running the Zowe server. This technique is known as **impersonation**. +Typically, the user `ZWESVUSR` that the Zowe server started task runs under needs to be able to change the security environment of its process to allow API requests to be issued on behalf of the logged on TSO user ID, rather than the server's user ID. This capability provides the functionality that allows users to log on to the Zowe desktop and use apps such as the File Editor to list data sets or USS files that the logged on user is authorized to view and edit, rather than the user ID running the Zowe server. This technique is known as **impersonation**. -To enable impersonation, you must grant the user ID `ZWESVUSR` associated with the `ZWESVSTC` started task UPDATE access to the `BPX.SERVER` and `BPX.DAEMON` profiles in the `FACILITY` class. +To enable impersonation, you must grant the user ID `ZWESVUSR` associated with the Zowe server started task UPDATE access to the `BPX.SERVER` and `BPX.DAEMON` profiles in the `FACILITY` class. -You can issue the following commands first to check whether you already have the impersonation profiles defined as part of another server configuration, such as the FTPD daemon. Review the output to confirm that the two impersonation profiles exist and the user `ZWESVUSR` who runs the `ZWESVSTC` started task has UPDATE access to both profiles. +You can issue the following commands first to check whether you already have the impersonation profiles defined as part of another server configuration, such as the FTPD daemon. Review the output to confirm that the two impersonation profiles exist and the user `ZWESVUSR` who runs the Zowe server started task has UPDATE access to both profiles. - If you use RACF, issue the following commands: ``` @@ -168,7 +171,7 @@ You can issue the following commands first to check whether you already have the LIST BPX ``` -If the user `ZWESVUSR` who runs the ZWESVSTC started task does not have UPDATE access to both profiles follow the instructions below. +If the user `ZWESVUSR` who runs the Zowe server started task does not have UPDATE access to both profiles follow the instructions below. - If you use RACF, complete the following steps: @@ -184,14 +187,14 @@ If the user `ZWESVUSR` who runs the ZWESVSTC started task does not have UPDATE a ``` RDEFINE FACILITY BPX.DAEMON UACC(NONE) ``` - 3. Having activated and RACLIST the FACILITY class, the user ID `ZWESVUSR` who runs the ZWESVSTC started task must be given update access to the BPX.SERVER and BPX.DAEMON profiles in the FACILITY class. + 3. Having activated and RACLIST the FACILITY class, the user ID `ZWESVUSR` who runs the Zowe server started task must be given update access to the BPX.SERVER and BPX.DAEMON profiles in the FACILITY class. ``` - PERMIT BPX.SERVER CLASS(FACILITY) ID() ACCESS(UPDATE) + PERMIT BPX.SERVER CLASS(FACILITY) ID() ACCESS(UPDATE) ``` ``` - PERMIT BPX.DAEMON CLASS(FACILITY) ID() ACCESS(UPDATE) + PERMIT BPX.DAEMON CLASS(FACILITY) ID() ACCESS(UPDATE) ``` - where is `ZWESVUSR` unless a different user ID is being used for the z/OS environment. + where is `ZWESVUSR` unless a different user ID is being used for the z/OS environment. /* Activate these changes */ @@ -207,17 +210,17 @@ If the user `ZWESVUSR` who runs the ZWESVSTC started task does not have UPDATE a ``` - If you use CA Top Secret, complete the following steps: - 1. Define the BPX Resource and access for . + 1. Define the BPX Resource and access for . ``` TSS ADD(`owner-acid`) IBMFAC(BPX.) ``` ``` - TSS PERMIT() IBMFAC(BPX.SERVER) ACCESS(UPDATE) + TSS PERMIT() IBMFAC(BPX.SERVER) ACCESS(UPDATE) ``` ``` - TSS PERMIT() IBMFAC(BPX.DAEMON) ACCESS(UPDATE) + TSS PERMIT() IBMFAC(BPX.DAEMON) ACCESS(UPDATE) ``` - where is `ZWESVUSR` unless a different user ID is being used for the z/OS environment. + where is `ZWESVUSR` unless a different user ID is being used for the z/OS environment. 2. Issue the following commands and review the output to check whether permission has been successfully granted: ``` TSS WHOHAS IBMFAC(BPX.SERVER) @@ -226,17 +229,17 @@ If the user `ZWESVUSR` who runs the ZWESVSTC started task does not have UPDATE a TSS WHOHAS IBMFAC(BPX.DAEMON) ``` - If you use CA ACF2, complete the following steps: - 1. Define the BPX Resource and access for . + 1. Define the BPX Resource and access for . ``` SET RESOURCE(FAC) ``` ``` - RECKEY BPX ADD(SERVER ROLE() SERVICE(UPDATE) ALLOW) + RECKEY BPX ADD(SERVER ROLE() SERVICE(UPDATE) ALLOW) ``` ``` - RECKEY BPX ADD(DAEMON ROLE() SERVICE(UPDATE) ALLOW) + RECKEY BPX ADD(DAEMON ROLE() SERVICE(UPDATE) ALLOW) ``` - where is `ZWESVUSR` unless a different user ID is being used for the z/OS environment. + where is `ZWESVUSR` unless a different user ID is being used for the z/OS environment. ``` F ACF2,REBUILD(FAC) ``` @@ -250,7 +253,7 @@ If the user `ZWESVUSR` who runs the ZWESVSTC started task does not have UPDATE a ## Configure address space job naming -The user ID `ZWESVUSR` that is associated with the Zowe started task `ZWESVSTC` must have `READ` permission for the `BPX.JOBNAME` profile in the `FACILITY` class. This is to allow setting of the names for the different z/OS UNIX address spaces for the Zowe runtime components. See [Address space names](configure-instance-directory.md#address-space-names). +The user ID `ZWESVUSR` that is associated with the Zowe started task must have `READ` permission for the `BPX.JOBNAME` profile in the `FACILITY` class. This is to allow setting of the names for the different z/OS UNIX address spaces for the Zowe runtime components. See [Address space names](configure-instance-directory.md#address-space-names). To display who is authorized to the profile, issue the following command: ``` @@ -268,7 +271,7 @@ For more information, see [Setting up the UNIX-related FACILITY and SURROGAT cla ## Configure multi-user address space (for TSS only) -The `ZWESVSTC` started task is multi-user address space, and therefore a TSS FACILITY needs to be defined and assigned to the started task. Then, all acids signing on to the started task will need to be authorized to the FACILITY. +The Zowe server started task either `ZWESVSTC` or `ZWESLSTC` is multi-user address space, and therefore a TSS FACILITY needs to be defined and assigned to the started task. Then, all acids signing on to the started task will need to be authorized to the FACILITY. The following example shows how to create a new TSS FACILITY. @@ -294,7 +297,7 @@ TSS ADD(user_acid) FAC(ZOWE) ## User IDs and groups for the Zowe started tasks -Zowe requires a user ID `ZWESVUSR` to execute its main z/OS runtime started task `ZWESVSTC`. This user ID must have a valid OMVS segment. +Zowe requires a user ID `ZWESVUSR` to execute its main z/OS runtime started task. This user ID must have a valid OMVS segment. Zowe requires a user ID `ZWESIUSR` to execute the cross memory server started task `ZWESISTC`. This user ID must have a valid OMVS segment. @@ -371,6 +374,38 @@ If you have not run `ZWESECUR` and are configuring your z/OS environment manuall TSS ADDTO(STC) PROCNAME(ZWESVSTC) ACID(ZWESVUSR) ``` +## Configure ZWESLSTC to run Zowe high availability instances under ZWESVUSR user ID + +You need Zowe started task `ZWESLSTC` for Zowe high availability. When the Zowe started task `ZWESLSTC` is started, it must be associated with the user ID `ZWESVUSR` and group `ZWEADMIN`. A different user ID and group can be used if required to conform with existing naming standards. + +If you have run `ZWESECUR`, you do not need to perform the steps described in this section, because they are executed during the JCL section of `ZWESECUR`. +``` +/* started task for ZOWE Launcher in high availability */ +... +``` + +If you have not run `ZWESECUR` and are configuring your z/OS environment manually, the following steps describe how to configure the started task `ZWESLSTC` to run under the correct user ID and group. + +- If you use RACF, issue the following commands: + ``` + RDEFINE STARTED ZWESLSTC.* UACC(NONE) STDATA(USER(ZWESVUSR) GROUP(ZWEADMIN) PRIVILEGED(NO) TRUSTED(NO) TRACE(YES)) + SETROPTS REFRESH RACLIST(STARTED) + ``` + +- If you use CA ACF2, issue the following commands: + + ``` + SET CONTROL(GSO) + INSERT STC.ZWESLSTC LOGONID(ZWESVUSR) GROUP(ZWEADMIN) STCID(ZWESLSTC) + F ACF2,REFRESH(STC) + ``` + +- If you use CA Top Secret, issue the following commands: + + ``` + TSS ADDTO(STC) PROCNAME(ZWESLSTC) ACID(ZWESVUSR) + ``` + ## Configure the cross memory server for SAF Zowe has a cross memory server that runs as an APF-authorized program with key 4 storage. Client processes accessing the cross memory server's services must have READ access to a security profile `ZWES.IS` in the `FACILITY` class. This authorization step is used to guard against access by non-priviledged clients. @@ -383,9 +418,9 @@ If you have run `ZWESECUR` you do not need to perform the steps described in thi If you have not run `ZWESECUR` and are configuring your z/OS environment manually, the following steps describe how to configure the cross memory server for SAF. -Activate the FACILITY class, define a `ZWES.IS` profile, and grant READ access to the user ID `ZWESVUSR`. This is the user ID that the Zowe started task `ZWESVSTC` runs under. +Activate the FACILITY class, define a `ZWES.IS` profile, and grant READ access to the user ID `ZWESVUSR`. This is the user ID that the main Zowe started task runs under. -To do this, issue the following commands that are also included in the `ZWESECUR` JCL member. The commands assume that you run the `ZWESVSTC` under the `ZWESVUSR` user. +To do this, issue the following commands that are also included in the `ZWESECUR` JCL member. The commands assume that you run the Zowe server under the `ZWESVUSR` user. - If you use RACF, issue the following commands: @@ -407,9 +442,9 @@ To do this, issue the following commands that are also included in the `ZWESECUR RDEFINE FACILITY ZWES.IS UACC(NONE) ``` ``` - PERMIT ZWES.IS CLASS(FACILITY) ID() ACCESS(READ) + PERMIT ZWES.IS CLASS(FACILITY) ID() ACCESS(READ) ``` - where `` is the user ID `ZWESVUSR` under which the ZWESVSTC started task runs. + where `` is the user ID `ZWESVUSR` under which the Zowe server started task runs. ``` SETROPTS RACLIST(FACILITY) REFRESH ``` diff --git a/docs/user-guide/configure-zowe-ha-server.md b/docs/user-guide/configure-zowe-ha-server.md new file mode 100644 index 0000000000..3ba90e35d6 --- /dev/null +++ b/docs/user-guide/configure-zowe-ha-server.md @@ -0,0 +1,60 @@ +# Installing and starting the Zowe high availability started task (ZWESLSTC) + +Zowe has a number of runtimes on z/OS: the z/OS Service microservice server, the Zowe Application Server, and the Zowe API Mediation Layer microservices. In a high availability environment, a single PROCLIB member `ZWESLSTC` is used to start multiple instances of a same component. This member is installed by Zowe into the SAMPLIB data set `SZWESAMP` during the installation from either a convenience build or an SMP/E build. + +This topic describes how to configure the z/OS runtime in order to launch Zowe for high availability instances. You can do these manually (as described in this topic) or use script to install and configure the Zowe launcher server. See [Installing and Configuring Zowe z/OS components using scripts](scripted-configure-server.md#zowe-z-os-components). + +## Step 1: Copy the PROCLIB member ZWESLSTC + +Zowe high availability instances are run under a z/OS started task with the PROCLIB member named `ZWESLSTC`. A sample PROCLIB member is created during installation into the PDS `SZWESAMP(ZWESLSTC)`. To launch high availability instances as a started task, you must copy this member to a PDS that is in the PROCLIB concatenation path. + +## Step 2: Configure ZWESLSTC to run under the correct user ID + +`ZWESLSTC` should be configured as a started task under the `ZWESVUSR `user ID with the administrator user ID of `ZWEADMIN`. If you do not have these IDs already created, you can find the commands to create the user ID and group in the PDS member `ZWESECUR`. See [Configuring the z/OS system for Zowe](configure-zos-system.md). To associate the `ZWESLSTC` started task with the user ID and group, see [Configuring a z/OS system for Zowe](configure-zos-system.md). This step is done once per z/OS environment by a system programmer who has sufficient security privileges. + +## Step 3: Launch the ZWESLSTC started task + +You launch the ZWESLSTC started task with the z/OS START command. + +### Before you begin + +Before starting ZWESLSTC, you need to perform the following steps in PROCLIB member `ZWESLSTC`: + +1. Set the parameter `INSTANCE_DIR` to the location (fully qualified path) of the Zowe instance directory that contains the `zowe.yaml` configuration file. +2. Update the STEPLIB DD statement with the location of the load library that contains the load module `ZWELNCH`. + +### Procedure + +You can start Zowe high availability instances by issuing the command `S ZWESLSTC` in SDSF. When you issue `S ZWESLSTC`, you must specify which high availability instance you want to launch by adding the `HAINST` parameter on the START command: + +``` +S ZWESLSTC,HAINST= +``` + +where, the `ha-instance-id` argument is the high availability instance ID that is defined in the `haInstances` section of the `zowe.yaml` configuration file. To learn more about `zowe.yaml`, see the [Updating the zowe.yaml configuration file](configure-instance-directory.md) section. + +This command enables you to start multiple instances of a same component, which eliminates single point of failure to ensure continuous operation of Zowe components. + +- If you want to have more than one Zowe high availability instance running concurrently, use the optional parameter `JOBNAME` with the START command to distinguish the Zowe high availability instances from each other. + + ``` + S ZWESLSTC,HAINST=,JOBNAME= + ``` + +- Zowe Launcher also enables you to restart a specific component of a high availability instance by using z/OS MODIFY command: + + ``` + F ZWESLSTC,APPL=START() + ``` + + where, the `ha-component-name` argument is the high availability instance component that is defined in the `components` section of `zowe.yaml` configuration file. To learn more about `zowe.yaml`, see the [Updating the zowe.yaml configuration file](configure-instance-directory.md) section. + +- If you specified the `JOBNAME=` parameter on the START command, the `instance-job-name` can be used with MODIFY command to restart a specific component: + + ``` + F ,APPL=START() + ``` + +### Next steps + +To check whether the ZWESLSTC started task has successfully launched, see [Troubleshooting installation and startup of Zowe z/OS components](../troubleshoot/troubleshoot-zos.md) for instructions. diff --git a/docs/user-guide/configure-zowe-server.md b/docs/user-guide/configure-zowe-server.md index 04e161e748..74fd20d50a 100644 --- a/docs/user-guide/configure-zowe-server.md +++ b/docs/user-guide/configure-zowe-server.md @@ -1,16 +1,16 @@ # Installing and starting the Zowe started task (ZWESVSTC) -Zowe has a number of runtimes on z/OS: the z/OS Service microservice server, the Zowe Application Server, and the Zowe API Mediation Layer microservices. A single PROCLIB `ZWESVSTC` is used to start all of these microservices. This member is installed by Zowe into the data set SAMPLIB `SZWESAMP` during the installation or either a convenience build or SMP/E. +Zowe has a number of runtimes on z/OS: the z/OS Service microservice server, the Zowe Application Server, and the Zowe API Mediation Layer microservices. A single PROCLIB member `ZWESVSTC` is used to start all of these microservices. This member is installed by Zowe into the SAMPLIB data set `SZWESAMP` during the installation either a convenience build or SMP/E. -This topic describes how to configure the z/OS runtime in order to launch Zowe. You can do these manually (as described in this topic) or use scripts to install and configure the cross memory server (see [Installing and Configuring Zowe z/OS components using scripts](scripted-configure-server.md#zowe-z-os-components). +This topic describes how to configure the z/OS runtime in order to launch Zowe. You can do these manually (as described in this topic) or use script to install and configure the Zowe main server. see [Installing and Configuring Zowe z/OS components using scripts](scripted-configure-server.md#zowe-z-os-components). ## Step 1: Copy the PROCLIB member ZWESVSTC -When the Zowe runtime is launched, it is run under a z/OS started task with the PROCLIB member named `ZWESVSTC`. A sample PROCLIB is created during installation into the PDS `SZWESAMP(ZWESVSTC)`. To launch Zowe as a started task, you must copy this member to a PDS that is in the proclib concatenation path. +When the Zowe runtime is launched, it is run under a z/OS started task with the PROCLIB member named `ZWESVSTC`. A sample PROCLIB is created during installation into the PDS `SZWESAMP(ZWESVSTC)`. To launch Zowe as a started task, you must copy this member to a PDS that is in the PROCLIB concatenation path. ## Step 2: Configure ZWESVSTC to run under the correct user ID -The `ZWESVSTC` should be configured as a started task under the `ZWESVUSR `user ID with the administrator user ID of `ZWEADMIN`. If you do not have these IDs already created, the commands to create the user ID and group are supplied in the PDS member `ZWESECUR`. See [Configuring the z/OS system for Zowe](configure-zos-system.md). To associate the `ZWESVSTC` started task with the user ID and group, see [Configuring a z/OS system for Zowe](configure-zos-system.md). This step will be done once per z/OS environment by a system programmer who has sufficient security privileges. +The `ZWESVSTC` should be configured as a started task under the `ZWESVUSR `user ID with the administrator user ID of `ZWEADMIN`. If you do not have these IDs already created, the commands to create the user ID and group are supplied in the PDS member `ZWESECUR`. See [Configuring the z/OS system for Zowe](configure-zos-system.md). To associate the `ZWESVSTC` started task with the user ID and group, see [Configuring a z/OS system for Zowe](configure-zos-system.md). This step will be done once per z/OS environment by a system programmer who has sufficient security privileges. ## Step 3: Launch the ZWESVSTC started task @@ -28,17 +28,17 @@ where, __ is the directory where you set the instance directory to. This script starts `ZWESVSTC` for you so you do not have to log on to TSO and use SDSF. -### Option 2: Starting Zowe with a `/S` TSO command +### Option 2: Starting Zowe with the z/OS START command You can use SDSF to start Zowe. -If you issue the SDSF command `/S ZWESVSTC`, the JCL will need to know the instance directory containing the launch and configuration information. To do this add the `INSTANCE` parameter on the START command when you start Zowe in SDSF: +If you issue z/OS command `S ZWESVSTC`, the JCL will need to know the instance directory containing the launch and configuration information. To do this add the `INSTANCE` parameter on the START command when you start Zowe in SDSF: ``` -/S ZWESVSTC,INSTANCE='$ZOWE_INSTANCE_DIR',JOBNAME='ZWEXSV' +S ZWESVSTC,INSTANCE='$ZOWE_INSTANCE_DIR',JOBNAME='ZWEXSV' ``` -The `$ZOWE_INSTANCE_DIR` argument is the fully qualifed path to the USS directory containing the `instance.env` file containing the Zowe configuration. +The `$ZOWE_INSTANCE_DIR` argument is the fully qualified path to the USS directory containing the `instance.env` file containing the Zowe configuration. The `JOBNAME='ZWEXSV'` argument is optional and the started task will operate correctly without it, however having it specified ensures that the address spaces will be prefixed with `ZWEXSV` which makes them easier to find in SDSF or locate in RMF records. diff --git a/docs/user-guide/configuring-docker.md b/docs/user-guide/configuring-docker.md index 72fcb1bf07..488fc536fa 100644 --- a/docs/user-guide/configuring-docker.md +++ b/docs/user-guide/configuring-docker.md @@ -92,7 +92,7 @@ If you have migrated the instance directory from z/OS, copied the simple instanc --env EXTERNAL_INSTANCE=/home/zowe/external_instance \ ``` -See [Creating and configuring the Zowe instance directory](configure-instance-directory.md#reviewing-the-instance-env-file) to review options for instance directory configuration. +See [Creating and configuring the Zowe instance directory](configure-instance-directory.md#updating-the-instance-env-configuration-file) to review options for instance directory configuration. ### Using external certificates diff --git a/docs/user-guide/install-docker-image.md b/docs/user-guide/install-docker-image.md index f0426f1d81..246647b3f4 100644 --- a/docs/user-guide/install-docker-image.md +++ b/docs/user-guide/install-docker-image.md @@ -9,7 +9,7 @@ To use this image, you must have set up the Zowe server runtime on z/OS, z/OSMF, If you have not set up the Zowe server runtime on z/OS, please follow the steps found in [Docker Installation Roadmap](install-docker.md). -This guide assumes you are using Linux or zLinux and have already downloaded Docker itself. If you have not yet done so, please review [System Requirements](systemrequirements.md). +This guide assumes you are using Linux or zLinux and have already downloaded Docker itself. If you have not yet done so, please review [System Requirements](systemrequirements-zos.md). ## Installing via Docker Hub @@ -19,7 +19,9 @@ You can download a Docker Image by using the Docker command line utility `docker - The latest version of zowe, `ompzowe/server-bundle:latest` - The latest version for the platform you are running on, such as `ompzowe/server-bundle:amd64` for Linux +- Older versions can be found with the version tag, such as `ompzowe/server-bundle:v1.20.0` - A specific version by referencing the version's digest, such as `ompzowe/server-bundle@sha256:bdbc0617b02e16a452f6d4de50b8b13e56592e309b4c68f9ea52c82303ad57ec` +- If you want the source code for all of the content in the image, that is available in the accompanying image with -sources prefix tag, such as `ompzowe/server-bundle:latest-sources` The latest digests can be seen on the [image's tags page](https://hub.docker.com/r/ompzowe/server-bundle/tags). diff --git a/docs/user-guide/install-ha-sysplex.md b/docs/user-guide/install-ha-sysplex.md new file mode 100644 index 0000000000..2c730fd346 --- /dev/null +++ b/docs/user-guide/install-ha-sysplex.md @@ -0,0 +1,159 @@ +# Zowe high availability installation roadmap (Technical Preview) + + Zowe™ high availability is a technical preview. Technical previews are for testing only and not ready for production. Any feedback that you can provide is highly appreciated. + +To install Zowe on a Sysplex, there are two parts: + +1. The Zowe runtime, which consists of the following components. An advanced launcher is used to perform the initialization and shutdown of these components. + + - Zowe Application Framework + - z/OS Explorer Services + - Zowe API Mediation Layer + - ZSS + +2. The Zowe Cross Memory Server, which is an authorized server application that provides privileged services to Zowe in a secure manner. + +Review the installation diagram and the high-level instructions in this topic to see the general installation sequence and the most important tasks that are to be performed during installation and configuration of Zowe high availability. You can click each step on the diagram for detailed instructions. + +
+ Click each step to get more details on the flow. +
+
+ + Plan and prepare for the installation + Configure system requirements + + Download Zowe SMP/E build + Install the Zowe SMP/E build using JCLs + Install the Zowe SMP/E build with z/OSMF workflow + + Download the Zowe convenience build + Verify, transfer, and expand the PAX file on z/OS + Install the Zowe runtime using shell script + Install the Zowe runtime with z/OSMF workflow + + Configure the z/OS system for Zowe using ZWESECUR + Create the VSAM data set for Caching Service + Configure Zowe certificates using shell script + Configure the Zowe cross memory server using shell script + Create and configure the Zowe instance directory using shell script + Create and customize Zowe YAML configuration file + Install and start the Zowe high availability started task using JCL + + Verify Zowe installation on z/OS + + +## Stage 1: Plan and prepare + +Before you start the installation, review the information on hardware and software requirements and other considerations. See [Planning the installation](installandconfig.md) for details. + +## Stage 2: Install the Zowe runtime + +1. Ensure that the software requirements are met. The prerequisites are described in [Zowe high availability requirements (host)](systemrequirements.md). + +1. Choose the method of installing Zowe high availability instances on a Sysplex. + + The Zowe z/OS binaries are distributed in the following formats. They contain the same contents but you install them by using different methods. You can choose which method to use depending on your needs. + + - **Convenience build** + + The Zowe z/OS binaries are packaged as a PAX file. You install this build by running shell script within a UNIX System Services (USS) shell. Convenience builds are full product installs. + + - **SMP/E build** + + The Zowe z/OS binaries are packaged as the following files that you can download. You install this build through SMP/E. + - A pax.Z file, which contains an archive (compressed copy) of the FMIDs to be installed. + - A readme file, which contains a sample job to decompress the pax.Z file, transform it into a format that SMP/E can process, and invoke SMP/E to extract and expand the compressed SMP/E input data sets. + + While the procedure to obtain and install the convenience build or SMP/E build are different, the procedure to configure a Zowe runtime are the same irrespective of how the build is obtained and installed. + +1. Obtain and install the Zowe build. + + - For how to obtain the convenience build and install it, see [Installing Zowe runtime from a convenience build](install-zowe-zos-convenience-build.md). + - For how to obtain the SMP/E build and install it, see [Installing Zowe SMP/E](install-zowe-smpe.md). + +**Note:** To allow all LPARs in a Sysplex to access the installation and configuration of Zowe high availability instances, you must install and configure Zowe in a shared file system (zFS directory). + +After successful installation of either a convenience build or an SMP/E build, there will be a shared zFS directory that contains the unconfigured Zowe runtime ``, a SAMPLIB library `SZWESAMP` that contains sample members, and a load library `SZWEAUTH` that contains load modules. + +## Stage 3: Configure the Zowe high availability runtime + +You can configure the Zowe high availability runtime by using JCL and shell scripts. + +**Tip:** It's recommended that you open the links in the following configuration procedure in new tabs. + +1. Configure the z/OS security manager to prepare for launching the Zowe started tasks. For instructions, see [Configuring the z/OS system for Zowe](configure-zos-system.md). + + A SAMPLIB JCL member `ZWESECUR` is provided to assist with the configuration. You can submit the `ZWESECUR` JCL member as-is or customize it depending on site preferences. + + If you already have this security step configured from a previous release of Version 1.8 or later, you only need to define Zowe launcher started task security configuration with the following commands. + + - If you use RACF, issue the following commands: + + ``` + RDEFINE STARTED &ZLNCHSTC..* + STDATA(USER(&ZOWEUSER.) GROUP(&STCGRP.) TRUSTED(NO)) + DATA('ZOWE LAUNCHER') + + SETROPTS RACLIST(STARTED) REFRESH + ``` + + - If you use CA ACF2, issue the following commands: + + ``` + SET CONTROL(GSO) + INSERT STC.&ZLNCHSTC. LOGONID(&ZOWEUSER.) + + GROUP(&STCGRP.) + + STCID(&ZLNCHSTC.) + + F ACF2,REFRESH(STC) + ``` + + - If you use CA Top Secret, issue the following commands: + + ``` + TSS ADD(STC) PROCNAME(&ZLNCHSTC.) ACID(&ZOWEUSER.) + + TSS ADD(&ZOWEUSER.) FAC(STC) + + ``` + + Where, + - ZLNCHSTC is the Zowe launcher task name. Default should be ZWESLSTC. + - STCGRP is the group for Zowe started tasks. Default should be ZWEADMIN. + - ZOWEUSER is the user ID for the Zowe started task. Default should be ZWESVUSR. + +2. Create a VSAM data set which is used by the Caching Service feature of API Mediation Layer. For instructions, see [Configuring Caching Service for HA](configure-caching-service-ha.md). + + A SAMPLIB JCL member `ZWECSVSM` is provided to assist with the creation of this VSAM data set. You need to customize the `ZWECSVSM` JCL member depending on your site preferences and then submit the JCL. + +3. Configure the Zowe TLS. For instructions, see [Configuring Zowe certificates](configure-certificates.md). + + The Zowe keystore directory must be created in a shared file system (zFS directory), so that it can be shared between all Zowe high availability instances running in a Sysplex. + + The Zowe keystore directory contains the key used by the Zowe desktop and the Zowe API mediation layer to secure its TLS communication with clients (such as web browsers or REST AI clients). The keystore directory also has a truststore where public keys of any servers that Zowe communicates to (such as z/OSMF) are held. + +4. Configure and start the `ZWESISTC` cross memory server and install the load libraries. For instructions, see [Installing and configuring the Zowe cross memory server (ZWESISTC)](configure-xmem-server.md). + +5. Create and customize an instance directory that contains the configuration data required to launch a Zowe runtime and is where log files and Zowe yaml configuration are stored. For instructions, see [Creating and configuring the Zowe instance directory](configure-instance-directory.md). + + One instance directory must be created on a shared file system (zFS directory). A single Zowe runtime can be launched multiple times from a shared instance directory. + +6. Create and customize the `/zowe.yaml` configuration file. To learn more about how to create `zowe.yaml`, see the [Creation of zowe.yaml file](configure-instance-directory.md#creation-of-zoweyaml-file) section. + + **Notes:** + + - To learn more about `zowe.yaml`, see the [Updating the zowe.yaml configuration file](configure-instance-directory.md) section. + - For more information about Gateway and Discovery Service parameters that can be set during the Zowe runtime configuration, see [API Gateway runtime configuration parameters](./api-mediation/api-gateway-configuration.md) and [Discovery Service runtime configuration parameters](./api-mediation/discovery-service-configuration.md). + +7. Configure and start the `ZWESLSTC` started task. For instructions, see [Installing and starting the Zowe high availability started task (ZWESLSTC)](configure-zowe-ha-server.md). + + Zowe in high availability mode has two high-level started tasks: `ZWESLSTC` that launches the Zowe high availability instances, and `ZWESISTC` that is a cross memory server that runs all of the APF-authorized code. The JCLs for the tasks are included in the PDS SAMPLIB `SZWESAMP` installed by Zowe and the load modules for the cross memory server are included in the PDS load library `SZWEAUTH`. + +## Stage 4: Verify the installation + +Verify that Zowe is installed correctly on z/OS. See [Verifying Zowe installation on z/OS](verify-zowe-runtime-install.md). + +## Looking for troubleshooting help? + +If you encounter unexpected behavior when installing or verifying the Zowe runtime on z/OS, see the [Troubleshooting](../troubleshoot/troubleshooting.md) section for tips. diff --git a/docs/user-guide/install-zos.md b/docs/user-guide/install-zos.md index 5f50df8879..394cad3d95 100644 --- a/docs/user-guide/install-zos.md +++ b/docs/user-guide/install-zos.md @@ -1,19 +1,18 @@ -# z/OS Installation Roadmap +# z/OS installation roadmap -There are two parts to installing Zowe™ on z/OS. +When you install Zowe™ on z/OS, you install the following two parts: -The first part is the Zowe runtime, consisting of the following components: +1. The Zowe runtime, which consists of the following components: + - Zowe Application Framework (ZLUX) + - Zowe API Mediation Layer + - Z Secure Services (ZSS) + - z/OS Explorer Services -- Zowe Application Framework -- z/OS Explorer Services -- Zowe API Mediation Layer -- ZSS +2. The Zowe Cross Memory Server, which is an APF authorized server application that provides privileged services to Zowe in a secure manner. -The second part is the Zowe Cross Memory Server, an authorized server application that provides privileged services to Zowe in a secure manner. +Zowe provides the ability for some of its unix components to be run not under USS, but as a Linux Docker container, see [Installing Zowe Server Components using Docker](install-docker.md). -If you want to use Docker, instead follow this related page: [Installing Zowe Server Components using Docker](install-docker.md). - -For more information on the Zowe components and how they are used to launch an instance of Zowe, see [Planning the installation](./installandconfig.md#planning-the-installation-of-zowe-z-os-components). +If you want to configure Zowe for high availability, see [Installing Zowe Server Components in Sysplex](install-ha-sysplex.md) for instructions. Review the installation diagram and the introduction in this topic to see the general installation sequence and the most important tasks that are to be performed during installation and configuration. You can click each step on the diagram for detailed instructions. @@ -54,7 +53,7 @@ Before you start the installation, review the information on hardware and softwa ## Stage 2: Install the Zowe z/OS runtime -1. Ensure that the software requirements are met. The prerequisites are described in [System requirements](systemrequirements.md). +1. Ensure that the software requirements are met. The prerequisites are described in [System requirements](systemrequirements-zos.md). 1. Choose the method of installing Zowe on z/OS. diff --git a/docs/user-guide/install-zowe-smpe.md b/docs/user-guide/install-zowe-smpe.md index b11322c044..4ef13cfef0 100644 --- a/docs/user-guide/install-zowe-smpe.md +++ b/docs/user-guide/install-zowe-smpe.md @@ -126,14 +126,27 @@ All issues of previous releases of Zowe that were resolved before August 2019 ha The Zowe SMP/E package is a distribution of Zowe version 1.9.0 with an FMID of AZWE001. -Subsequent releases of the Zowe z/OS components are delivered as rollup PTFs on [zowe.org](https://www.zowe.org/download.html). Because of the file size of the PTF, it is packaged as two co-requisite PTFs, which are made available in a single Zip file. +Subsequent releases of the Zowe z/OS components are delivered as rollup PTFs on [zowe.org](https://www.zowe.org/download.html). +- Prior to version 1.19.0, the Zowe release is packaged as two co-requisite PTFs, which are made available in a single Zip file. +- With the continuous optimization of the Zowe build size, starting with version 1.19.1, the Zowe release is packaged as one single PTF. + Zowe release | PTF 1 | PTF 2 ---|---|--- -[1.10](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.10.0) | UO01939 | UO01940 -[1.11](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.11.0) | UO01942 | UO01943 -[1.12](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.12.0) | UO01945 | UO01946 -[1.13](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.13.0) | UO01948 | UO01949 +[1.10.0](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.10.0) | UO01939 | UO01940 +[1.11.0](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.11.0) | UO01942 | UO01943 +[1.12.0](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.12.0) | UO01945 | UO01946 +[1.13.0](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.13.0) | UO01948 | UO01949 +[1.14.0](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.14.0) | UO01951 | UO01952 +[1.15.0](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.15.0) | UO01953 | UO01954 +[1.16.0](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.16.0) | UO01955 | UO01956 +[1.17.0](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.17.0) | UO01958 | UO01959 +[1.18.0](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.18.0) | UO01965 | UO01966 +[1.19.0](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.19.0) | UO01967 | UO01968 +[1.19.1](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.19.1) | UO01969 | +[1.20.0](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.20.0) | UO01970 | +[1.20.1](https://zowe.jfrog.io/zowe/list/libs-release-local/org/zowe/download/legal.html?type=smpe&version=1.20.1) | UO01980 | + ## Installation requirements and considerations diff --git a/docs/user-guide/installandconfig.md b/docs/user-guide/installandconfig.md index 71c452515f..bb285ae402 100755 --- a/docs/user-guide/installandconfig.md +++ b/docs/user-guide/installandconfig.md @@ -4,42 +4,38 @@ The installation of Zowe™ consists of two independent processes: installin The Zowe server components provide a web desktop that runs in a web browser providing a number of applications for z/OS users, together with an API mediation layer provides single-sign on (SSO), organization of the multiple zowe servers under a single website, and other capabilities useful for z/OS developers. -Zowe CLI can connect to z/OS servers and allows tasks to be performed through a command line interface. - Because Zowe is a set of components, before installing Zowe, first determine which components you want to install and where you want to install them. This guide provides documentation for all of the components and it is split into sections so you can install as much as you need. Here are some scenarios to consider: -- If you will only be accessing the Zowe server components through a web browser or REST API client, then you do not need to install the Zowe CLI. -- If you will only be using the Zowe CLI, depending on the plugins used you may not need to install the Zowe server components. -- If you intend to use Docker for the server components, less components need to be installed on z/OS. If you are not using the Desktop or ZSS, then it's possible run the other Zowe components without installing any of Zowe onto z/OS. +- If you will only be using the Zowe CLI on PCs, depending on the plugins being used, you may not need to install the Zowe server components. If you are just using core Zowe CLI groups from your PC, the z/OS you connect to does not required any components of Zowe to be installed on z/OS, unless you want to take advantage of advanced authentication methods such as single sign-on or multi-factor authentication. +- If you are using the Docker technical preview to run the linux parts of Zowe in a container, then you only need to configure Zowe's z/OS component to start the ZSS server. Before you start the installation, review the information on system requirements and other considerations. -## Planning the installation of Zowe server components - -All Zowe server components can be installed on z/OS, but some have the alternative option of being run inside of a Docker image on a Linux host. -Which option you choose effects the prerequisites, where they are installed, and the installation steps needed. +## Planning z/OS installation -### Planning z/OS installation +The following information is required during the installation process. Software and hardware prerequisites are covered in the next section. -If you are installing one or more server components onto z/OS, 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](configure-uss.md). +- 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](configure-uss.md). - 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. +- 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. +- (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 two 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](configure-xmem-server.md). - - `ZWESVSTC` brings up the every other other part of the Zowe runtime on z/OS that was requested. This may include Desktop, API mediation layer, ZSS, and more, but when using Docker likely only ZSS will be used here. +- 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](configure-xmem-server.md). + - `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](configure-xmem-server.md) + - `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 the two started tasks to run correctly, security manager configuration needs to be performed. This is documented in [Configuring the z/OS system for Zowe](configure-zos-system.md) and a sample JCL member `ZWESECUR` is shipped with Zowe that contains commands for RACF, TopSecret, and ACF2 security managers. + 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](configure-zos-system.md) and a sample JCL member `ZWESECUR` is shipped with Zowe that contains commands for RACF, TopSecret, and ACF2 security managers. -**Note:** To start the API Mediation Layer as a standalone component, see [API Mediation Layer as a standalone component](api-mediation-standalone.md) +**Note:** To start the API Mediation Layer as a standalone component, see [API Mediation Layer as a standalone component](api-mediation-standalone.md). ## Topology of the Zowe z/OS launch process @@ -58,15 +54,17 @@ During execution of Zowe, the runtime directory contents are not modified. Main ### INSTANCE_DIR -The instance directory `` is required to launch Zowe. It is created with the script `/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 ``. +The instance directory `` is required to launch Zowe. It is created with the script `/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 ``. -Zowe instances are started by running the script `/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. +Zowe instances are started by running the script `/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 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 `` 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](configure-instance-directory.md). + -Zowe uses certificates to encrypt data as well as a truststore. The keystore directory `` controls where the certificates are located, either in a JavaKeystore or a z/OS keyring. A `` is created by using the script `/bin/zowe-setup-certificates.sh`. +### KEYSTORE_DIRECTORY +Zowe uses certificates to encrypt data as well as a truststore. The keystore directory `` controls where the certificates are located, either in a JavaKeystore or a z/OS keyring. A `` is created by using the script `/bin/zowe-setup-certificates.sh`. \ No newline at end of file diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 113b3e0ff5..0368bc4221 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -619,7 +619,7 @@ For information on endpoint URLs, see [Dataservice endpoint URL lengths and RBAC As of Zowe version 1.8.0, the Zowe App Framework, Desktop, and all apps present in the SMP/E or convenience builds support [out-of-band MFA](https://www.ibm.com/support/knowledgecenter/SSNR6Z_2.0.0/com.ibm.mfa.v2r0.azfu100/azf_oobconcepts.htm) by entering an MFA assigned token or passcode into password field of the Desktop login screen, or by accessing the app-server `/auth` REST API endpoint. -For a list of compatible MFA products, see [Known compatible MFA products](systemrequirements.md#known-compatible-mfa-products) +For a list of compatible MFA products, see [Known compatible MFA products](systemrequirements-zos.md#multi-factor-authentication-mfa). ### Session duration and expiration diff --git a/docs/user-guide/scripted-configure-server.md b/docs/user-guide/scripted-configure-server.md index 85aeafa2ee..21adbd4c2e 100644 --- a/docs/user-guide/scripted-configure-server.md +++ b/docs/user-guide/scripted-configure-server.md @@ -1,6 +1,8 @@ # Installing and configuring Zowe z/OS components using scripts -A Zowe installation creates two PDS sample libraries, `SZWEAUTH` and `SZWESAMPE`. Before starting the two Zowe started tasks `ZWESVSTC` (for the main Zowe z/OS components), and `ZWESISTC` (for the cross memory server), you must complete additional configuration steps as described in [Installing and starting the Zowe started task (ZWESVSTC)](configure-zowe-server.md) and [Installing and configuring the Zowe cross memory server (ZWESISTC)](configure-xmem-server.md). +A Zowe installation creates two PDS sample libraries, `SZWEAUTH` and `SZWESAMP`. Before starting the two Zowe started tasks for the main Zowe z/OS components and the cross memory server, you must complete additional configuration steps as described in + - [Installing and starting the Zowe started task (ZWESVSTC)](configure-zowe-server.md) or [Installing and starting the Zowe high availability started task (ZWESLSTC)](configure-zowe-ha-server.md) + - [Installing and configuring the Zowe cross memory server (ZWESISTC)](configure-xmem-server.md) Zowe provides UNIX shell scripts to assist with installation and configuration for scenarios where you wish to automate this process, for example if you have a DevOps pipeline or other repeatable scenario where you are installing and starting a Zowe runtime. These are the same scripts used by the Zowe community themselves for the automated Zowe continuous integration continuous delivery (CICD) pipeline which creates Zowe releases. @@ -10,7 +12,7 @@ The script `/scripts/utils/zowe-install-proc.sh -d - **`-d `** - Source PDS Prefix - Dataset prefix of the source PDS where `.SZWESAMP(ZWESVSTC)` was installed into. + Dataset prefix of the source PDS `.SZWESAMP` where Zowe was installed into. For an installation from a convenience build, this will be the value of the `-h` argument when `zowe-install.sh` was executed. @@ -18,7 +20,7 @@ The script `/scripts/utils/zowe-install-proc.sh -d - **`-r `** - Target PROCLIB PDS (optional) - Target PROCLIB PDS where ZWESVSTC will be placed. If the parameter is omitted, the script scans the JES PROCLIB concatenation path and uses the first data set where the user has write access + Target PROCLIB PDS where Zowe server started task procedure will be placed. If the parameter is omitted, the script scans the JES PROCLIB concatenation path and uses the first data set where the user has write access - **`-l `** - Log directory (optional) @@ -35,11 +37,11 @@ The script `/scripts/utils/zowe-install-xmem.sh -d - **`-d `** - Source PDS prefix. - This is the data set prefix of the source PDS where `.SZWESAMP` was installed into. + This is the data set prefix of the source PDS `.SZWESAMP` where Zowe was installed into. - **`-a `** - Target DSN for PARMLIB (optional) - This is the data set name where the PARMLIB member `ZWESIP00` will be placed. If the parameter is omitted, then source data set `SZWESAMP` will be used by the started task PROCLIB `ZWESISTC`. If `-a` is set, then the `EXEC DD PARMLIB=` statement in the JCL PROCLIB `ZWESISTC` will be updated. + This is the data set name where the PARMLIB member `ZWESIP00` will be placed. If the parameter is omitted, then source data set `.SZWESAMP` will be used by the started task PROCLIB `ZWESISTC`. If `-a` is set, then the `EXEC DD PARMLIB=` statement in the JCL PROCLIB `ZWESISTC` will be updated. - **`-r `** - Target PROCLIB PDS where `ZWESASTC` and `ZWESISTC` will be placed. diff --git a/docs/user-guide/stop-zowe-zos.md b/docs/user-guide/stop-zowe-zos.md index 23c577c363..15e5cbbc9e 100644 --- a/docs/user-guide/stop-zowe-zos.md +++ b/docs/user-guide/stop-zowe-zos.md @@ -1,12 +1,16 @@ -# Stopping the ZWESVSTC PROC +# Stopping the Zowe server started task -To stop the Zowe server, the ZWESVSTC PROC needs to be ended. Run the `zowe-stop.sh` script at the Unix Systems Services command prompt that is in the zowe instance directory used to start the Zowe started task: +Learn how to stop the Zowe server started tasks ZWESVSTC and ZWESLSTC. + +## Stopping the ZWESVSTC started task + +To stop the Zowe server, the ZWESVSTC started task needs to be ended. Run the `zowe-stop.sh` script at the Unix Systems Services command prompt that is in the zowe instance directory used to start the Zowe started task: ``` cd $ZOWE_INSTANCE_DIR/bin ./zowe-stop.sh ``` -where __ is the directory where you set the instance directory to. +where `ZOWE_INSTANCE_DIR` is the directory where you set the instance directory to. When you stop ZWESVSTC, you might get the following error message: @@ -14,13 +18,42 @@ When you stop ZWESVSTC, you might get the following error message: IEE842I ZWESVSTC DUPLICATE NAME FOUND- REENTER COMMAND WITH 'A=' ``` -This error results when there is more than one started task named ZWESVSTC. To resolve the issue, stop the required ZWESVSTC instance by issuing the following commands: +This error occurs when there is more than one started task named ZWESVSTC. To resolve the issue, stop the required ZWESVSTC instance by issuing the following commands: + +``` +C ${ZOWE_PREFIX}${ZOWE_INSTANCE}SV,A=asid +``` + +Where `ZOWE_PREFIX` and `ZOWE_INSTANCE` are specified in your configuration (and default to ZWE and 1) and you can obtain the `asid` from the value of `A=asid` when you issue the following commands: + +``` +D A,${ZOWE_PREFIX}${ZOWE_INSTANCE}SV +``` + +## Stopping the ZWESLSTC started task + +z/OS STOP command is used to terminate the Zowe launcher server (ZWESLSTC) which started the Zowe high availability instance. You can use SDSF to end ZWESLSTC with the following command: ``` -/C ${ZOWE_PREFIX}${ZOWE_INSTANCE}SV,A=asid +P ZWESLSTC ``` -Where _ZOWE_PREFIX_ and _ZOWE_INSTANCE_ are specified in your configuration (and default to ZWE and 1) and you can obtain the _asid_ from the value of `A=asid` when you issue the following commands: + +The `instance-job-name` specified in the `JOBNAME=` parameter of the Zowe launcher START command can be used to terminate the relevant high availability instance. See [Installing and starting the Zowe high availability started task (ZWESLSTC)](configure-zowe-ha-server.md) for more information. + +``` +P +``` + +Zowe Launcher also enables you to stop a specific component of a running high availability instance by using the z/OS MODIFY command: + +``` +F ZWESLSTC,APPL=STOP() +``` + +The `ha-component-name` argument is the high availability instance component that is defined in the `components` section of the `zowe.yaml` configuration file. To learn more about `zowe.yaml`, see the [Updating the zowe.yaml configuration file](configure-instance-directory.md) section. + +The `instance-job-name` specified in the `JOBNAME=` parameter of the Zowe launcher START command can be used to terminate a specific component of a running high availability instance: ``` -/D A,${ZOWE_PREFIX}${ZOWE_INSTANCE}SV +F ,APPL=STOP() ``` \ No newline at end of file diff --git a/docs/user-guide/systemrequirements-cli.md b/docs/user-guide/systemrequirements-cli.md new file mode 100644 index 0000000000..ca5b58356b --- /dev/null +++ b/docs/user-guide/systemrequirements-cli.md @@ -0,0 +1,39 @@ +# System requirements + +Before installing Zowe™ CLI, ensure that your environment meets the prerequisites. + +- [Client-side](#client-side) +- [Host-side](#host-side) +- [Free disk space](#free-disk-space) + +## Client-side + +Zowe CLI is supported on Windows, Linux, and Mac operating systems. Meet the following requirements before you install the CLI: + +- **Node.js:** Install a currently supported Node.js LTS version. For an up-to-date list of supported LTS versions, see [Nodejs.org](https://nodejs.org/en/about/releases/). + + ::: tip + You might need to restart the command prompt after installing Node.js. Issue the command `node --version` to verify that Node.js is installed. + ::: + +- **npm:** Install a version of Node Package Manager (npm) that is compatible with your version of Node.js. + + ::: tip + Npm is included with most Node.js installations. Issue the command `npm --version` to check your current version. You can reference the [Node.js release matrix](https://nodejs.org/en/download/releases/) to verify that the versions are compatible. + ::: + +- **Plug-in client requirements:** If you plan to install plug-ins, review the [Software requirements for CLI plug-ins](./cli-swreqplugins.md). You *must* meet the client requirements for the Secure Credential Store and IBM Db2 plug-ins prior to installing them. + +## Host-side + +Zowe CLI requires the following mainframe configuration: + +- **IBM z/OSMF configured and running:** You do not need to install the full Zowe solution to install and use Zowe CLI. Minimally, an instance of IBM z/OSMF must be running on the mainframe before you can issue Zowe CLI commands successfully. z/OSMF enables the core capabilities such as retrieving data sets, executing TSO commands, submitting jobs, and more. If Zowe API Mediation Layer (API ML) is configured and running, CLI users can choose to connect to API ML rather than to every separate service. + +- **Plug-in services configured and running:** Plug-ins communicate with various mainframe services, which must be configured and running on the mainframe prior to issuing plug-in commands. For example, the IMS plug-in requires an instance of IBM IMS on the mainframe with IMS Connect (REST services) running. For more information, see [Software requirements for CLI plug-ins](./cli-swreqplugins.md) + +- **Zowe CLI on z/OS is not supported:** Zowe CLI can be installed on an IBM z/OS environment and run under Unix System Services (USS). However, the IBM Db2 and Secure Credentials Store plug-ins will *not* run on z/OS due to native code requirements. As such, Zowe CLI is *not supported on z/OS* and is currently experimental. + +## Free disk space + +Zowe CLI requires approximately **100 MB** of free disk space. The actual quantity of free disk space consumed might vary depending on your operating system, the plug-ins that you install, and user profiles saved to disk. \ No newline at end of file diff --git a/docs/user-guide/systemrequirements-zos.md b/docs/user-guide/systemrequirements-zos.md new file mode 100644 index 0000000000..bea2f9f24d --- /dev/null +++ b/docs/user-guide/systemrequirements-zos.md @@ -0,0 +1,175 @@ +# System requirements + +Before installing Zowe™ z/OS components, ensure that your z/OS environment meets the prerequisites. The prerequisites you need to install depend on what Zowe z/OS components you want to use and how you want to install and configure Zowe on z/OS. Therefore, assess your installation scenario and install the prerequisites that meet your needs. + +All Zowe server components can be installed on a z/OS environment, while some can alternatively be installed on Linux or zLinux via Docker. The components provide a number of services that are accessed through a web browser such as an API catalog and a web desktop. + +- [z/OS system requirements](#zos-system-requirements) + - [z/OS](#zos) + - [Node.js](#nodejs) + - [Java](#java) + - [z/OSMF (Optional)](#zosmf-optional) +- [User ID requirements](#user-id-requirements) + - [ZWESVUSR](#zwesvusr) + - [ZWESIUSR](#zwesiusr) + - [ZWEADMIN](#zweadmin) + - [zowe_user](#zowe_user) +- [Network requirements](#network-requirements) +- [Zowe Docker requirements](#zowe-docker-requirements) +- [Zowe Desktop requirements (client PC)](#zowe-desktop-requirements-client-pc) +- [Feature requirements](#feature-requirements) + - [Multi-Factor Authentication MFA](#multi-factor-authentication-mfa) + - [Single Sign-On SSO](#single-sign-on-sso) + +## z/OS system requirements + +Be sure your z/OS system meets the following prerequisites. + +### z/OS + +- z/OS version in active support, such as Version 2.3 and Version 2.4 + + **Note:** z/OS V2.2 reached end of support on 30 September 2020. For more information, see the z/OS v2.2 lifecycle details [https://www.ibm.com/support/lifecycle/details?q45=Z497063S01245B61](https://www.ibm.com/support/lifecycle/details?q45=Z497063S01245B61). + +- zFS volume with at least 833 mb of free space for Zowe server components, their keystore, instance configuration files and logs, and third-party plug-ins. + +- (Optional, recommended) z/OS OpenSSH V2.2.0 or later + + Some features of Zowe require SSH, such as the Desktop's SSH terminal. Or, you want to install and manage Zowe via SSH, as an alternative to OMVS over TN3270. + +- (Optional, recommended) Parallel Sysplex. + + To deploy Zowe for high availability, a Parallel Sysplex environment is recommended. Please check [Configuring Sysplex for high availability](configure-sysplex.md) for more information. + +### Node.js + +- Node.js v8.x (except v8.16.1), v12.x, or v14 + + Node is not included with z/OS so must be installed separately. To install Node.js on z/OS, follow the instructions in [Installing Node.js on z/OS](install-nodejs-zos.md). + + **Note:** If you are a software vendor building extensions for Zowe, when using Node.js v12.x or later, it is highly recommended that plug-ins used are tagged. For more information, see [Tagging on z/OS](../extend/extend-desktop/mvd-buildingplugins.md#tagging-plugin-files-on-z-os). + +### Java + +- IBM SDK for Java Technology Edition V8 or later + +### z/OSMF (Optional) + +- (Optional, recommended) IBM z/OS Management Facility (z/OSMF) Version 2.2, Version 2.3 or Version 2.4. + + z/OSMF is included with z/OS so does not need to be separately installed. If z/OSMF is present, Zowe will detect this when it is configured and use z/OSMF for the following purposes: + + - Authenticating TSO users and generating a single sign-on JSON Web Token (JWT). Ensure that the [z/OSMF JWT Support is available via APAR and associated PTFs](https://www.ibm.com/support/pages/apar/PH12143). If z/OSMF is not available, then Zowe is still able to provide SSO by generating its own JWT and making direct SAF calls. + + - REST API services for Files (Data Sets and USS), JES, and z/OSMF workflows. These are used by some Zowe applications such as the Zowe Explorers in the Zowe Desktop. If z/OSMF REST APIs are not present, other Zowe desktop application, such as the File Editor that provides access to USS directories and files as well as MVS data sets and members, will work through the Zowe Z Secure Services (ZSS) component to access z/OS resources. + + **Tips:** + + - For non-production use of Zowe (such as development, proof-of-concept, demo), you can customize the configuration of z/OSMF to create what is known as "z/OS MF Lite" that simplifies the setup of z/OSMF. As z/OS MF Lite only supports selected REST services (JES, DataSet/File, TSO and Workflow), you will observe considerable improvements in startup time as well as a reduction in the efforts involved in setting up z/OSMF. For information about how to set up z/OSMF Lite, see [Configuring z/OSMF Lite (non-production environment)](systemrequirements-zosmf-lite.md). + - For production use of Zowe, see [Configuring z/OSMF](systemrequirements-zosmf.md). + + +## User ID requirements + +Specific user IDs with sufficient permissions are required to run or access Zowe. + +### ZWESVUSR + +This is a started task ID used to run the PROCLIB `ZWESVSTC`. + +The task starts a USS environment using `BPXBATSL` that executes the core Zowe Desktop (ZLUX) node.js server, the Java API Mediation Layer, and the Z Secure Services C component. To work with USS, the user ID `ZWESVUSR` must have a valid OMVS segment. + +| Class | ID | Access | Reason | +|--------|--------|--------|---------| +| CSFSERV | `CSFRNGL` | READ | To generate symmetric keys using ICSF that is used by [Zowe Desktop cookies](./configure-zos-system.md#configure-an-icsf-cryptographic-services-environment) | +| FACILITY | `ZWES.IS` | READ | To allow Zowe ZWESVSTC processes to access the Zowe ZIS cross memory server | +| FACILITY | `BPX.SERVER` + `BPX.DEAMON` | UPDATE | To allow the Zowe Desktop ZLUX server to run code on behalf of the API requester's TSO user ID. For more information, see [Security Environment Switching](./configure-zos-system.md#configure-security-environment-switching). | +| FACILITY | `IRR.RUSERMAP` | READ | To allow Zowe to [map an X.509 client certificate to a z/OS identity](./configure-zos-system.md#configure-main-zowe-server-to-use-identity-mapping) | +| FACILITY | `BPX.JOBNAME` | READ | To allow z/OS address spaces for unix processes to be renamed for [ease of identification](./configure-zos-system.md#configure-address-space-job-naming) | + +### ZWESIUSR + +This is a started task ID used to run the PROCLIB `ZWESISTC` that launches the [cross memory server](./configure-xmem-server.md) (also known as ZIS). It must have a valid OMVS segment. + +### ZWEADMIN + +This is a group that `ZWESVUSR` and `ZWESIUSR` should belong to. It must have a valid OMVS segment. + +### zowe_user + +If z/OSMF is used for authentication and serving REST APIs for Zowe CLI and Zowe Explorer users, the TSO user ID for end users must belong to one or both of the groups `IZUUSER` or `IZUADMIN`. + +## Network requirements + +The following ports are required for Zowe. These are default values. You can change the values by updating variable values in the `instance.env` file. For more information, see [Configuring the Zowe instance directory](configure-instance-directory.md#updating-the-instance-env-configuration-file). + +| Port number | Variable name | Purpose | +|------|------|------| +| 7552 | _CATALOG_PORT_ | Used to view API swagger / openAPI specifications for registered API services in the API Catalog. +| 7553 | _DISCOVERY_PORT_ | Discovery server port which dynamic API services can issue APIs to register or unregister themselves. +| 7554 | _GATEWAY_PORT_ | The northbound edge of the API Gateway used to accept client requests before routing them to registered API services. This port must be exposed outside the z/OS network so clients (web browsers, VS Code, processes running the Zowe CLI) can reach the gateway. +| 7555 | _ZWE_CACHING_SERVICE_PORT_ | Port of the caching service that is used to share state between different Zowe instances in a high availability topology. +| 8545 | _JOBS_API_PORT_ | Port of the service that provides REST APIs to z/OS jobs used by the JES Explorer. +| 8546 | _JES_EXPLORER_UI_PORT_ | Port of the JES Explorer GUI for viewing and working with jobs in the Zowe Desktop. +| 8547 | _FILES_API_PORT_ | Port of the service that provides REST APIs to MVS and USS file systems. +| 8548 | _MVS_EXPLORER_UI_PORT_ | Port of the MVS Explorer GUI for working with data sets in the Zowe Desktop. +| 8550 | _USS_EXPLORER_UI_PORT_ | Port of the USS Explorer GUI for working with USS in the Zowe Desktop. +| 8544 | _ZOWE_ZLUX_SERVER_HTTPS_PORT_ | The Zowe Desktop (also known as ZLUX) port used to log in through web browsers. +| 8542 | _ZOWE_ZSS_SERVER_PORT_ | Z Secure Services (ZSS) provides REST API services to ZLUX, used by the File Editor application and other ZLUX applications in the Zowe Desktop. + +## Zowe Docker requirements + + The Zowe Docker build is a technical preview. + +Docker is a technology for delivering a set of software and all its prerequisites and run them in an isolated manner to reduce installation steps and to eliminate troubleshooting environmental differences. +Docker can run on many operating systems, but currently the Zowe Docker image is for x86 Linux (Intel, AMD) and zLinux ("s390x"). Support for platforms such as zCX, Windows, and more will be added over time. + +To get Docker for Linux, you should check your Linux software repository. Whether using Ubuntu, Red Hat, SuSE, and many other types of Linux, you can install Docker the same way you install other software on Linux through the package manager. + +Once you have Docker, the Zowe Docker image has the following requirements + +- 4 GB free RAM, 8 GB recommended +- 4 GB free disk space +- Network access to the z/OS host. The Linux host must be able to communicate with the z/OS host. + +When using Docker the USS components of Zowe will run off z/OS in the Linux container, however a z/OS installation of Zowe is still required for the ZSS and cross memory server. + +**Note:** The subsections of z/OS requirements such as for API Mediation Layer, Web Explorers, and Application Framework are not required because they are included in the Docker install. + +## Zowe Desktop requirements (client PC) + +The Zowe Desktop is powered by the Application Framework which has server prereqs depending on where it is installed +- [Zowe Application Framework on z/OS requirements](#zowe-application-framework-on-zos-requirements) +- [Application Framework on Docker prerequisites](#docker-requirements-host) + +The Zowe Desktop runs inside of a browser. No browser extensions or plugins are required. +The Zowe Desktop supports Google Chrome, Mozilla Firefox, Apple Safari and Microsoft Edge releases that are at most 1 year old, except when the newest release is older. +For Firefox, both the regular and Extended Support Release (ESR) versions are supported under this rule. + +Currently, the following browsers are supported: +- Google Chrome V79 or later +- Mozilla Firefox V68 or later +- Safari V13 or later +- Microsoft Edge 79 + +If you do not see your browser listed here, please contact the Zowe community so that it can be validated and included. + +## Feature requirements + +Zowe has several optional features that have additional prerequisites as follows. + +### Multi-Factor Authentication (MFA) + +Multi-factor authentication is supported for several components, such as the Desktop and API Mediation Layer. +Multi-factor authentication is provided by third-party products which Zowe is compatible with. The following are known to work: +- [IBM Z Multi-Factor Authentication](https://www.ibm.com/us-en/marketplace/ibm-multifactor-authentication-for-zos). + +For information on using MFA in Zowe, see [Multi-Factor Authentication](mvd-configuration.md#multi-factor-authentication-configuration). + +### Single Sign-On (SSO) + +Zowe has an SSO scheme with the goal that each time you use use multiple Zowe components you should only be prompted to login once. + +Requirements: +- IBM z/OS Management Facility (z/OSMF) +- (Optional, recommended) PKCS#11 token setup is required when using ZSS, the Desktop, and Application Framework with SSO. See [Creating a PKCS#11 Token](configure-certificates.md#creating-a-pkcs11-token) for more information. \ No newline at end of file diff --git a/docs/user-guide/systemrequirements-zosmf-ha.md b/docs/user-guide/systemrequirements-zosmf-ha.md new file mode 100644 index 0000000000..59b86cceee --- /dev/null +++ b/docs/user-guide/systemrequirements-zosmf-ha.md @@ -0,0 +1,103 @@ +# Configuring z/OSMF for high availability in Sysplex + +z/OSMF high availability (HA) should be configured in Hot Standby mode to ensure availability of REST services. The goal of this configuration is to ensure that one z/OSMF server is always available to provide the REST services. + +In Hot Standby mode, there is at least one backup (hot-standby) server and a preferred target server. Both targets are active, and both z/OSMF servers are bound to the DVIPA. The preferred z/OSMF server receives all new incoming requests. When the preferred z/OSMF server fails or the system becomes down, new requests are routed to the backup (hot-standby) server. The distributing DVIPA does not perform load balancing of requests across multiple systems. For more information, read the following articles in IBM Documentation: + +- [Configuring z/OSMF for availability](https://www.ibm.com/docs/en/zos/2.2.0?topic=environment-configuring-zosmf-availability) +- [Configuring z/OSMF for high availability](https://www.ibm.com/docs/en/zos/2.4.0?topic=configurations-configuring-zosmf-high-availability) + + +## Sysplex environment requirements + +Before you begin, ensure that the Sysplex environment meets the following requirements for z/OSMF REST services: + +- Shared SAF database. See [Sharing a database with sysplex communication in data sharing mode](https://www.ibm.com/docs/en/zos/2.1.0?topic=sd-sharing-database-sysplex-communication-in-data-sharing-mode) in IBM Documentation. +- USS Shared file system. See [How to share file systems in a Sysplex](https://www.ibm.com/docs/en/zos/2.4.0?topic=planning-sharing-file-systems-in-sysplex) in IBM Documentation. +- JESPlex/JES2 Multi-Access Spool (MAS) environment +- Sysplex distributor, configured Dynamic VIPA TCP/IP address +- Extended MCS console (EMCS) + +## Setting up z/OSMF nucleus + +**This information is intended for a first-time z/OSMF setup.** Follow these high-level steps to create a z/OSMF nucleus on your system. + +For detailed information about each step, see [Create a z/OSMF nucleus on your system](https://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.izua300/izulite_CreateTheNucleus.htm) in IBM Documentation. + +1. Create the z/OSMF security authorizations by running the sample JCL **SYS1.SAMPLIB(IZUSEC)**. z/OSMF security authorizations will be used by all z/OSMF servers across multiple systems. + +2. Create a shared file system per z/OSMF server by running the sample JCL **SYS1.SAMPLIB(IZUMKFS)**. It holds configuration settings and the persistence data. + +3. Copy the Sample Parmlib Member **SYS1.SAMPLIB(IZUPRM00)** to PARMLIB and modify it according to [requirements of z/OSMF HA parmlib member in Sysplex](#requirements-of-zosmf-ha-parmlib-member-in-sysplex). Each system uses a different IZUPRMxx member. For example, IZUPRM0A and IZUPRM0B. + +4. Copy the following z/OSMF procedures from **SYS1.PROCLIB** into your JES concatenation: + - IZUSVR1 (Each z/OSMF server should use the different started procedure. For example, IZUSVRA and IZUSVRB.) + - IZUANG1 + - IZUFPROC + +5. Define different STARTED profiles for z/OSMF servers. + + +### Requirements of z/OSMF HA parmlib member in Sysplex + +- _AUTOSTART_GROUP_, more than one z/OSMF server (independent z/OSMF instances) is to be autostarted in a Sysplex. For instance, System A will autostart a server and similarly, System B will autostart the second z/OSMF server. + + z/OSMF has a default autostart group (IZUDFLT) which is used in monoplex or single z/OS image. To have more z/OSMF servers autostarted in a Sysplex, you must associate each server and the systems it serves with a unique autostart group name. For example, `AUTOSTART_GROUP('IZUDFLA')` for System A and `AUTOSTART_GROUP('IZUDFLB')` for System B + +- _AUTOSTART(LOCAL)_ should be used by all z/OSMF instances. + +- _HOSTNAME_, the DVIPA address will be used as the z/OSMF host name for all instances. + +- _HTTP_SSL_PORT_, all servers are listening on the same port. + +- _KEYRING_NAME_, all servers should use the same key ring such as `IZUKeyring.IZUDFLT`. + +- _SERVER_PROC_, each z/OSMF server should use the different started procedure. For example, IZUSVRA and IZUSVRB. + +- _ANGEL_PROC_, all z/OSMF servers can connect to the same z/OSMF angel process such as IZUANG1. + +- _SAF_PREFIX_, they should use the same SAF profile prefix such as IZUDFLT. + +- _USER_DIR_, each instance uses a shared file system with a unique mount point for each AUTOSTART group that be automatically started. For example, `/global/zosmf/zosmfa` and `/global/zosmf/zosmfb`. + +## Configuring z/OSMF for high availability + +The following DVIPA configuration ensures the availability of z/OSMF for Hot-Standby. For example, suppose that you have a Sysplex of two z/OS systems: A, B. + +1. Enable dynamic XCF on each host by adding the following TCP/IP definitions: + - `IPCONFIG SYSPLEXROUTING DYNAMICXCF x.x.x.A 255.255.255.0 1` for SYSA + - `IPCONFIG SYSPLEXROUTING DYNAMICXCF x.x.x.B 255.255.255.0 1` for SYSB + +2. Define a dynamic VIPA (DVIPA) for both systems: + ``` + VIPADYNAMIC + VIPADEFINE 255.255.255.0 x.x.x.V + VIPADISTRIBUTE DEFINE DISTM HOTSTANDBY x.x.x.V + PORT 443 DESTIP + x.x.x.A PREFERRED + x.x.x.B BACKUP + ENDVIPADYNAMIC + ``` + + where, + - x.x.x.A is the home address for SYSA. + - x.x.x.B is the home address for SYSB. + - x.x.x.V is Dynamic VIP Address. + + ![](../images/zosmf/zOSMF-HA.png) + +The `VIPADISTRIBUTE` statement with `PREFERRED` and `BACKUP` settings is used to enable automatic dynamic VIPA takeover to occur, if needed. + +Both z/OSMF servers are bound to the DVIPA x.x.x.V. With both z/OS systems active in the Sysplex, the preferred z/OSMF server, SYSA receives all new incoming requests. +If SYSA fails, new work requests for z/OSMF are routed to the server on SYSB. When SYSA resumes normal operations, new work requests for z/OSMF are routed to SYSA again. This is the default behavior because the `AUTOSWITCHBACK` parameter of the `VIPADISTRIBUTE` statement is in effect by default. + +If you do not want the distributor to switch back to the preferred target when it becomes available, you can specify the `NOAUTOSWITCHBACK` parameter for the `VIPADISTRIBUTE` statement. +``` +VIPADYNAMIC + VIPADEFINE 255.255.255.0 x.x.x.V + VIPADISTRIBUTE DEFINE DISTM HOTSTANDBY NOAUTOSWITCHBACK x.x.x.V + PORT 443 DESTIP + x.x.x.A PREFERRED + x.x.x.B BACKUP +ENDVIPADYNAMIC +``` \ No newline at end of file diff --git a/docs/user-guide/systemrequirements.md b/docs/user-guide/systemrequirements.md index 742c53fc73..8979f6e9af 100644 --- a/docs/user-guide/systemrequirements.md +++ b/docs/user-guide/systemrequirements.md @@ -1,189 +1,6 @@ # System requirements -Before installing Zowe™, ensure that your environment meets the prerequisites. +Select which component you want to install and view the system requirements based on your option: -- [z/OS system requirements (host)](#zos-system-requirements-host) - - [Zowe API Mediation Layer on z/OS requirements](#zowe-api-mediation-layer-on-zos-requirements-host) - - [Zowe Web Explorers and APIs on z/OS requirements](#zowe-web-explorers-and-apis-on-zos-requirements-host) - - [Zowe Application Framework on z/OS requirements](#zowe-application-framework-on-zos-requirements-host) - - [Important note for users upgrading to v1.14](#important-note-for-users-upgrading-to-v114) -- [Docker requirements](#docker-requirements-host) -- [Zowe Desktop requirements](#zowe-desktop-requirements-client) -- [Zowe CLI requirements](#zowe-cli-requirements) - - [Client-side](#client-side) - - [Host-side](#host-side) - - [Free disk space](#free-disk-space) -- [Feature requirements](#feature-requirements) - - [Multi-Factor Authentication (MFA)](#multi-factor-authentication-mfa) - - [Single Sign-On (SSO)](#single-sign-on-sso) - - -**Please note: Not all of the prerequisites below are needed. The prerequisites needed depends on what components you want to use.** - -Zowe CLI operates independently of the Zowe z/OS component and is installed on a client PC that runs Windows, Linux, or Mac operating systems. It can access z/OS endpoints such as z/OSMF, or can access FTP, CICS, DB2, and other z/OS services through plug-ins. Unless required by plug-ins, the Zowe CLI does not require the Zowe server components to be installed. - -All Zowe server components can be installed on a z/OS environment, while some can alternatively be installed on Linux or zLinux via Docker. The components provide a number of services that are accessed through a web browser such as an API catalog and a web desktop. The client PC that accesses the Zowe server components does not need to have the Zowe CLI installed. - -Even though the Zowe server components do not require the CLI and vice-versa, there is an advantage to having the server components if using the CLI. When installed, the API Mediation Layer of Zowe can provide benefits to the CLI such as single-sign-on and only needing to trust a single certificate when using multiple Zowe-related endpoints. - -For more information on the relationship between the Zowe server components and Zowe CLI, see [Zowe overview](../getting-started/overview.md). - - -## z/OS system requirements (host) - -- z/OS version in active support, such as Version 2.3 and Version 2.4 - - **Note:** z/OS V2.2 reaches end of support on 30 September 2020. For more information, see the z/OS v2.2 lifecycle details [https://www.ibm.com/support/lifecycle/details?q45=Z497063S01245B61](https://www.ibm.com/support/lifecycle/details?q45=Z497063S01245B61). Zowe Version 1.15 and earlier can continue to work with z/OS V2.2 but you are advised to upgrade your z/OS to more recent versions. - -- zFS volume with at least 833mb of free space for Zowe server components, their keystore, instance configuration files and logs, and third party plugins. - **Requirement for:** Zowe Server Components (API Mediation Layer, Application Framework, ZSS) - -- (Optional, recommended) IBM z/OS Management Facility (z/OSMF) Version 2.2, Version 2.3 or Version 2.4. - While z/OSMF is optional for Zowe, many components utilize it and therefore it is recommended that z/OSMF is present to fully exploit Zowe's capabilities. - - When utilizing z/OSMF with Zowe ensure the [z/OSMF JWT Support is available via APAR and associated PTFs](https://www.ibm.com/support/pages/apar/PH12143). - -- (Optional, recommended) z/OS OpenSSH V2.2.0 or higher. - Some features of Zowe require SSH, such as the Desktop's SSH terminal. - Some users may also find it convenient to install & manage Zowe via SSH, as an alternative to OMVS over TN3270. - - ::: tip - - For non-production use of Zowe (such as development, proof-of-concept, demo), you can customize the configuration of z/OSMF to create what is known as "z/OS MF Lite" that simplifies the setup of z/OSMF. As z/OS MF Lite only supports selected REST services (JES, DataSet/File, TSO and Workflow), you will observe considerable improvements in startup time as well as a reduction in the efforts involved in setting up z/OSMF. For information about how to set up z/OSMF Lite, see [Configuring z/OSMF Lite (non-production environment)](systemrequirements-zosmf-lite.md). - - For production use of Zowe, see [Configuring z/OSMF](systemrequirements-zosmf.md). - ::: - - -### Zowe API Mediation Layer on z/OS requirements (host) - -- IBM SDK for Java Technology Edition V8 or later - -### Zowe Web Explorers and APIs on z/OS requirements (host) - -- Node.js v8.x (except v8.16.1), v12.x, or v14 - - **Note:** When using Node.js v12.x or later, it is highly recommended that plug-ins used are tagged. For more information, see [Tagging on z/OS](../extend/extend-desktop/mvd-buildingplugins.md#tagging-plugin-files-on-z-os). - - To install Node.js on z/OS, follow the instructions in [Installing Node.js on z/OS](install-nodejs-zos.md). - -- IBM SDK for Java Technology Edition V8 or later - -### Zowe Application Framework on z/OS requirements (host) - -The Zowe Application Framework server provides the Zowe Desktop that contains an extensible GUI with a number of applications allowing access to z/OS functions, such as the File Editor, TN3270 emulator, JES Explorer, and more. For more information, see [Zowe Architecture](../getting-started/zowe-architecture.md#zlux). - -- Node.js v8.x (except v8.16.1), v12.x, or v14 - - **Note:** When using Node.js v12.x or later, it is highly recommended that plug-ins used are tagged. For more information, see [Tagging on z/OS](../extend/extend-desktop/mvd-buildingplugins.md#tagging-plugin-files-on-z-os). - - To install Node.js on z/OS, follow the instructions in [Installing Node.js on z/OS](install-nodejs-zos.md). - -- IBM SDK for Java Technology Edition V8 or later - - -### Important note for users upgrading to v1.14 - -If you are upgrading to Zowe v1.14 from a previous release, -and the value of `ZOWE_EXPLORER_HOST` does not match the host and domain that you put into your browser to access Zowe, you must update your configuration due to updated referrer-based security. - -To configure your system for the version 1.14 update, perform **one** of the following tasks: -- Define `ZWE_EXTERNAL_HOSTS` as a comma-separated list of hosts from which you would access Zowe from your browser. - - `ZWE_EXTERNAL_HOSTS=host1,host2,...` - -- Define `ZWE_REFERRER_HOSTS` as a comma-separated list for the value to be applied specifically for referrer purposes. - - `ZWE_REFERRER_HOSTS=host1,host2,...` - -See [Reviewing the instance env file](../user-guide/configure-instance-directory.md#reviewing-the-instanceenv-file) for additional information on the use of `instance.env` files. - -See [Configuring a Zowe instance via instance.env file](../user-guide/configure-instance-directory.md#configuring-a-Zowe-instance-via-instanceenv-file) for additional information on configuring `instance.env` files. - -## Docker requirements (host) - - The Zowe Docker build is a technical preview. - -Docker is a technology for delivering a set of software and all its prerequisites and run them in an isolated manner to reduce installation steps and to eliminate troubleshooting environmental differences. -Docker can run on many operating systems, but currently the Zowe Docker image is for x86 Linux (Intel, AMD) and zLinux ("s390x"). Support for platforms such as zCX, Windows, and more will be added over time. - -To get Docker for Linux, you should check your Linux software repository. Whether using Ubuntu, Red Hat, SuSE, and many other types of Linux, you can install Docker the same way you install other software on Linux through the package manager. - -Once you have Docker, the Zowe Docker image has the following requirements - -- 4 GB free RAM, 8 GB recommended -- 4 GB free disk space -- Network access to the z/OS host. The Linux host must be able to communicate with the z/OS host. - -When using Docker, z/OS is still required and if using the Application Framework or ZSS, installing ZSS on the z/OS host is still required. See these requirements: -- [z/OS system requirements](#zos-system-requirements-host) - -**Note:** The subsections of z/OS requirements such as for API Mediation Layer, Web Explorers, and Application Framework are not required because they are included in the Docker install. - -## Zowe Desktop requirements (client) - -The Zowe Desktop is powered by the Application Framework which has server prereqs depending on where it is installed -- [Application Framework on z/OS prerequisites](#zowe-application-framework-requirements-host) -- [Application Framework on Docker prerequisites](#docker-requirements-host) - -The Zowe Desktop runs inside of a browser. No browser extensions or plugins are required. -The Zowe Desktop supports Google Chrome, Mozilla Firefox, Apple Safari and Microsoft Edge releases that are at most 1 year old, except when the newest release is older. -For Firefox, both the regular and Extended Support Release (ESR) versions are supported under this rule. - -Currently, the following browsers are supported: - - Google Chrome V79 or later - - Mozilla Firefox V68 or later - - Safari V13 or later - - Microsoft Edge 79 - -If you do not see your browser listed here, please contact the Zowe community so that it can be validated and included. - -## Zowe CLI requirements - -### Client-side - -Zowe CLI is supported on Windows, Linux, and Mac operating systems. Meet the following requirements before you install the CLI: - -- **Node.js:** Install a currently supported Node.js LTS version. For an up-to-date list of supported LTS versions, see [Nodejs.org](https://nodejs.org/en/about/releases/). - - ::: tip - You might need to restart the command prompt after installing Node.js. Issue the command `node --version` to verify that Node.js is installed. - ::: - -- **npm:** Install a version of Node Package Manager (npm) that is compatible with your version of Node.js. - - ::: tip - Npm is included with most Node.js installations. Issue the command `npm --version` to check your current version. You can reference the [Node.js release matrix](https://nodejs.org/en/download/releases/) to verify that the versions are compatible. - ::: - -- **Plug-in client requirements:** If you plan to install plug-ins, review the [Software requirements for CLI plug-ins](./cli-swreqplugins.md). You *must* meet the client requirements for the Secure Credential Store and IBM Db2 plug-ins prior to installing them. - -### Host-side - -Zowe CLI requires the following mainframe configuration: - -- **IBM z/OSMF configured and running:** You do not need to install the full Zowe solution to install and use Zowe CLI. Minimally, an instance of IBM z/OSMF must be running on the mainframe before you can issue Zowe CLI commands successfully. z/OSMF enables the core capabilities such as retrieving data sets, executing TSO commands, submitting jobs, and more. If Zowe API Mediation Layer (API ML) is configured and running, CLI users can choose to connect to API ML rather than to every separate service. - -- **Plug-in services configured and running:** Plug-ins communicate with various mainframe services, which must be configured and running on the mainframe prior to issuing plug-in commands. For example, the IMS plug-in requires an instance of IBM IMS on the mainframe with IMS Connect (REST services) running. For more information, see [Software requirements for CLI plug-ins](./cli-swreqplugins.md) - -- **Zowe CLI on z/OS is not supported:** Zowe CLI can be installed on an IBM z/OS environment and run under Unix System Services (USS). However, the IBM Db2 and Secure Credentials Store plug-ins will *not* run on z/OS due to native code requirements. As such, Zowe CLI is *not supported on z/OS* and is currently experimental. - -### Free disk space - -Zowe CLI requires approximately **100 MB** of free disk space. The actual quantity of free disk space consumed might vary depending on your operating system, the plug-ins that you install, and user profiles saved to disk. - -## Feature requirements - -Zowe has several optional features that have additional prerequisites as follows. - -### Multi-Factor Authentication (MFA) - -Multi-factor authentication is supported for several components, such as the Desktop and API Mediation Layer. -Multi-factor authentication is provided by third party products which Zowe is compatible with. The following are known to work: -- [IBM Z Multi-Factor Authentication](https://www.ibm.com/us-en/marketplace/ibm-multifactor-authentication-for-zos). - -For information on using MFA in Zowe, see [Multi-Factor Authentication](mvd-configuration.md#multi-factor-authentication-configuration). - -### Single Sign-On (SSO) - -Zowe has an SSO scheme with the goal that each time you use use multiple Zowe components you should only be prompted to login once. - -Requirements: -- IBM z/OS Management Facility (z/OSMF) -- (Optional, recommended) PKCS#11 token setup is required when using ZSS, the Desktop, and Application Framework with SSO. See [Creating a PKCS#11 Token](configure-certificates.md#creating-a-pkcs11-token) for more information. +- [Install Zowe z/OS components](systemrequirements-zos.md) +- [Install Zowe CLI](systemrequirements-cli.md) diff --git a/docs/user-guide/upgrade-zos-system.md b/docs/user-guide/upgrade-zos-system.md index 82ca828dae..4d7df29488 100644 --- a/docs/user-guide/upgrade-zos-system.md +++ b/docs/user-guide/upgrade-zos-system.md @@ -25,7 +25,7 @@ After installing a new version of Zowe, the new runtime will either be in the sa In both situations, you can keep and reuse the instance directory that is used for the previous version of Zowe to launch the new version of Zowe. To do this, run the script `zowe-configure-instance.sh` from the new `/bin` directory with the `-c` argument pointing to the location of the existing instance directory. This is the same method used to create an instance directory with default values in an empty target directory, however if `-c` argument is a pre-existing instance directory rather than wiping and creating fresh contents, the contents are updated. In the situation where the previous instance directory was created from a different runtime directory, the `ROOT_DIR=` value in `instance.env` will be updated to reference the `` from which `zowe-configure-instance.sh` was executed. In addition the `manifest.json` file in the instance directory will be updated with the `"version:"` of the ``. This can be used as a way to see the Zowe version that an instance was last configured from. See [Check the Zowe release number](../troubleshoot/troubleshoot-zowe-release.md#check-the-zowe-release-number). -The `zowe-configure-instance.sh` script will detect if there are new configuration values that have been introduced since the instance directory was last created, and append these to `instance.env` with default values. New values added will be echoed in the shell running the `zowe-configure-instance.sh` script, and are be described in [Reviewing the instance.env file](./configure-instance-directory.md#reviewing-the-instance.env-file). Values in `instance.env` previously changed from their default, such as port values or locations of dependent runtimes, are not modified. +The `zowe-configure-instance.sh` script will detect if there are new configuration values that have been introduced since the instance directory was last created, and append these to `instance.env` with default values. New values added will be echoed in the shell running the `zowe-configure-instance.sh` script, and are be described in [Updating the instance.env configuration file](./configure-instance-directory.md#updating-the-instance-env-configuration-file). Values in `instance.env` previously changed from their default, such as port values or locations of dependent runtimes, are not modified. The `zowe-configure-instance.sh` script will echo any values that are added to the `instance.env` file. @@ -33,6 +33,21 @@ The `zowe-configure-instance.sh` script will echo any values that are added to t Missing properties that will be appended to /u/winchj/zowe-instance/instance.env: ``` +### Important note for users upgrading to v1.14 + +If you are upgrading to Zowe v1.14 (or higher) from a previous release, and the value of `ZOWE_EXPLORER_HOST` does not match the host and domain that you put into your browser to access Zowe, you must update your configuration due to updated referrer-based security. + +To configure your system for the version 1.14 update, perform **one** of the following tasks to update the `instance.env` configuration file: +- Define `ZWE_EXTERNAL_HOSTS` as a comma-separated list of hosts from which you would access Zowe from your browser. + - `ZWE_EXTERNAL_HOSTS=host1,host2,...` + +- Define `ZWE_REFERRER_HOSTS` as a comma-separated list for the value to be applied specifically for referrer purposes. + - `ZWE_REFERRER_HOSTS=host1,host2,...` + +See [Updating the instance.env configuration file](../user-guide/configure-instance-directory.md#updating-the-instance-env-configuration-file) for additional information on the use of `instance.env` files. + +See [Configuring a Zowe instance via instance.env file](../user-guide/configure-instance-directory.md#configuring-a-Zowe-instance-via-instanceenv-file) for additional information on configuring `instance.env` files. + ## Updating the PROCLIB members Zowe releases contain two proclib members, `ZWESISTC` and `ZWESVSTC` in the PDS `SZWESAMP`. When the previous release of Zowe was installed, these would have been copied to a PDS in the proclib concatenation path and defined to run under their respective user IDs of `ZWESVUSR` and `ZWESIUSR`. See [Installing the Zowe started task (ZWESVSTC)](./configure-zowe-server.md) and [Installing the Zowe cross memory server (ZWESISTC)](./configure-xmem-server.md). diff --git a/docs/user-guide/zowe-zos-uninstall.md b/docs/user-guide/zowe-zos-uninstall.md index 07ed5c5b83..5a86dc381a 100644 --- a/docs/user-guide/zowe-zos-uninstall.md +++ b/docs/user-guide/zowe-zos-uninstall.md @@ -4,47 +4,51 @@ You can uninstall Zowe™ from z/OS if you no longer need to use it. **Follow these steps:** -1. Stop the Zowe started task which stops all of its microservices by using the following command: +1. Stop the Zowe started task which stops all of its microservices. See [Stopping Zowe Server started task](stop-zowe-zos.md) + + After Zowe has been stopped, its subcomponents will end which include API Mediation Layer and the Zowe desktop. + + To make sure that all Zowe subcomponents are ended, you can check either SDSF, DA (Active users) or SDSF, PS (Processes) panel for `ZWE*` address spaces. If any Zowe zombie processe is still running, cancel them either from SDSF, DA panel or from USS command line by using the following commands: ``` - /C ${ZOWE_PREFIX}${ZOWE_INSTANCE}SV + su + ps -elf | grep ZWESVUSR | awk '{print $2}' | xargs kill -9 ``` - Where ZOWE_PREFIX and ZOWE_INSTANCE are specified in your configuration (and default to ZWE and 1), see [Zowe instance directory](configure-instance-directory.md#address-space-names) - - After Zowe has been stopped it's subcomponents will end which include the API Mediation Layer and the Zowe desktop. -2. Delete the `ZWESVSTC` member from your system `PROCLIB` data set. +2. Delete the Zowe PROCLIB member from your system `PROCLIB` data set. To do this, you can issue the following TSO DELETE command from the TSO READY prompt or from ISPF option 6: ``` - delete 'your.zowe.proclib(zwesvstc)' + delete 'your.zowe.proclib(zowe-proclib-member)' ``` Alternatively, you can issue the TSO DELETE command at any ISPF command line by prefixing the command with TSO: ``` - tso delete 'your.zowe.proclib(zwesvstc)' - ``` + tso delete 'your.zowe.proclib(zowe-proclib-member)' + ``` + + Where `zowe-proclib-member` can be either `ZWESVSTC` or `ZWESLSTC` - To query which PROCLIB data set that ZWESVSTC is put in, you can view the SDSF JOB log of ZWESVSTC and look for the following message: + To query which PROCLIB data set that Zowe PROCLIB member is put in, you can view the SDSF JOB log of Zowe started task and look for the following message: ``` - IEFC001I PROCEDURE ZWESVSTC WAS EXPANDED USING SYSTEM LIBRARY your.zowe.proclib + IEFC001I PROCEDURE `zowe-proclib-member` WAS EXPANDED USING SYSTEM LIBRARY `your.zowe.proclib` ``` - If no ZWESVSTC JOB log is available, issue the `/$D PROCLIB` command at the SDSF COMMAND INPUT line and BROWSE each of the `DSNAME=some.jes.proclib` output lines in turn with ISPF option 1, until you find the first data set that contains member ZWESVSTC. Then, issue the DELETE command as shown above. + If no Zowe started task JOB log is available, issue the JES2 command `$D PROCLIB` at SDSF COMMAND INPUT line and BROWSE each of the `DSNAME=some.jes.proclib` output lines in turn with ISPF option 1, until you find the first data set that contains Zowe PROCLIB member. Then, issue the DELETE command as shown above. - After you have removed `ZWESVSTC` from the `PROCLIB` data set it will no longer be possible to start Zowe instances. + After you have removed PROCLIB member from the `PROCLIB` data set it will no longer be possible to start Zowe instances. 3. Remove the USS folders containing the Zowe artifacts. - Remove the USS folders containing the Zowe runtime, the Zowe keystore-directory, and the Zowe instance directories. + Remove the USS folders containing the Zowe runtime, the Zowe keystore-directory, and the Zowe instance directories. 4. Reverse the z/OS security and environment updates from `ZWESECUR` job. - As part of Zowe installation, the z/OS environment is altered to allow Zowe to operate. See [Configuring the z/OS System for Zowe](configure-zos-system.md#configuring-the-z-os-system-for-zowe) for details. You may leave the environment configured which allows you to install and operate a Zowe instance at a point in the future, or you may undo the configuration steps to your z/OS environment. Zowe provides a JCL member `ZWENOSEC` that contains the commands needed to reset a z/OS environment and undo the steps that were performed in `ZWESECUR` when the environment was configured for Zowe operation. + As part of Zowe installation, the z/OS environment is altered to allow Zowe to operate. See [Configuring the z/OS System for Zowe](configure-zos-system.md#configuring-the-z-os-system-for-zowe) for details. You may leave the environment configured which allows you to install and operate a Zowe instance at a point in the future, or you may undo the configuration steps to your z/OS environment. Zowe provides a JCL member `ZWENOSEC` that contains the commands needed to reset a z/OS environment and undo the steps that were performed in `ZWESECUR` when the environment was configured for Zowe operation. -5. Reverse the z/OS key ring updates from `ZWEKRING` job. +5. Reverse the z/OS key ring updates from `ZWEKRING` job. - The `ZWEKRING` JCL member provided in the `SZWESAMP` member can be used to create a key ring that contains the Zowe certificate(s) and certificate authority. If you want to remove the key ring and its certificate(s) and certificate authority, you can use the JCL member `ZWENOKYR` that contains the undo steps to reverse the configuration performed in `ZWEKRING`. \ No newline at end of file + The `ZWEKRING` JCL member provided in the `SZWESAMP` member can be used to create a key ring that contains the Zowe certificate(s) and certificate authority. If you want to remove the key ring and its certificate(s) and certificate authority, you can use the JCL member `ZWENOKYR` that contains the undo steps to reverse the configuration performed in `ZWEKRING`. \ No newline at end of file