From 84255ed66fe6052e6d5b700199895d4e2cd517af Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Wed, 8 Nov 2023 06:11:42 -0500 Subject: [PATCH 01/67] Update mvd-server-config.md Signed-off-by: 1000TurquoisePogs --- .../extend-desktop/mvd-server-config.md | 43 ++++++------------- 1 file changed, 14 insertions(+), 29 deletions(-) diff --git a/docs/extend/extend-desktop/mvd-server-config.md b/docs/extend/extend-desktop/mvd-server-config.md index bc9a67423e..65e2ddb774 100644 --- a/docs/extend/extend-desktop/mvd-server-config.md +++ b/docs/extend/extend-desktop/mvd-server-config.md @@ -1,15 +1,17 @@ The Zowe's App Server and ZSS rely on many required or optional parameters to run, which includes setting up networking, deployment directories, plugin locations, and more. -These parameters can be specified in multiple ways: configuration files, CLI arguments, or environment variables. -Every configuration option and requirement is documented within the application framework [json-schema file](https://github.com/zowe/zlux/blob/v2.x/staging/schemas/zlux-config-schema.json) -# Configuration file -In Zowe's server configuration file, app-server parameters can be specified within `components.app-server` as shown in the component [json-schema file](https://github.com/zowe/zlux/blob/v2.x/staging/schemas/zowe-schema.json), or `components.zss` for ZSS. +# Configuration File +The servers use a YAML file for configuration. The [global schema](https://github.com/zowe/zowe-install-packaging/blob/v2.x/staging/schemas/zowe-yaml-schema.json) describes the parts of configuration that are common between servers. +The App Server specifically is configured by the `components.app-server` section of the YAML, and that section follows [this App-server schema](https://github.com/zowe/zlux-app-server/blob/v2.x/staging/schemas/app-server-config.json) +ZSS is instead configured by the `components.zss` section, following [the ZSS schema](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json) +The App server can additionally use CLI arguments or environment variables to override the YAML file. -# Environment variables +# Environment variables (app-server only) CLI arguments take precedence over the configuration file, but are overridden by the CLI arguments. The format is `ZWED_key=value`, where "ZWED_" is a prefix for any configuration object. -The key maps to a YAML object attribute, so to set the value of a nested object, such as the https configuration, you need multiple values. +The attributes specified will be put within the `components.app-server` subsection of the Zowe configuration. +The key maps to a JSON object attribute, so to set the value of a nested object, such as the https configuration, you need multiple values. For example: ``` node: @@ -54,16 +56,9 @@ ZWED_logLevels_org____zowe____terminal____tn3270_x2e_x2a:5 * strings can have quotes, but otherwise everything that isnt an array, boolean, or number is a string * objects are never values. They are the keys. -## Friendly names for environment variables -Some common configuration options have names that do not follow the above special syntax. These options get mapped to the special syntax when the server runs, so the same behavior can be configured in more than one way. Many of these values are listed here https://docs.zowe.org/stable/user-guide/configure-zowe-zosmf-workflow/#configure-the-zowe-instance-directory but for the App Server, the code that maps these values is contained within https://github.com/zowe/zlux-app-server/blob/v2.x/master/bin/convert-env.sh - - -Although overridden by both environment variables and CLI arguments, for convenience the App server and ZSS read from a configuration file with a common structure. ZSS reads this directly as a startup argument, while the App Server as defined in the [zlux-server-framework](https://github.com/zowe/zlux-server-framework) repository accepts several parameters which are intended to be read from a YAML file through an implementer of the server, such the default provided in the [zlux-app-server](https://github.com/zowe/zlux-app-server) repository, namely the [lib/zluxServer.js](https://github.com/zowe/zlux-app-server/blob/v2.x/master/lib/zluxServer.js) file. This file accepts a YAML file that specifies most if not all parameters needed, but some other parameters can be provided via flags if desired. - - # CLI arguments (app-server only) CLI arguments take precedence over environment variable and configuration files. -The format is `--key=value` +The format is `--key=value` and the attributes specified will be put within the `components.app-server` subsection of the Zowe configuration. The key maps to a YAML object attribute, so to set the value of a nested object, such as the https configuration, you need multiple period-separated values. For example: ``` @@ -86,7 +81,7 @@ node.https.certificates="../defaults/serverConfig/server.cert" **NOTE: ZSS does not support CLI arguments** -**The key name is case-sensitive.** +**The key names are case-sensitive.** **The types of the values are syntax-sensitive.** * Numbers are treated as numbers, not strings. @@ -142,18 +137,8 @@ To include Apps, be sure to define the location of the Plugins directory in the For more information, see [Logging Utility](mvd-logutility.md). ## ZSS Configuration -When running ZSS, it will require a configuration file similar or the same as the one used for the App Server. The attributes that are needed for ZSS, at minimum, are: *productDir*, *siteDir*, *instanceDir*, *groupsDir*, *usersDir*, *pluginsDir* and **agent**. All of these attributes have the same meaning as described above for the App server, but if the App server and ZSS are not run from the same location, then these directories may be different if desired. - -### ZSS Networking - -The attributes that control ZSS exclusively are within the **agent** object. ZSS uses HTTPS by default, but for those who wish to use AT-TLS instead of the built-in HTTPS support, ZSS can use HTTP as well. HTTP should never be used without [AT-TLS](../../user-guide/mvd-configuration#defining-the-at-tls-rule), as this is a security risk. The values `agent.https.port`, `agent.http.port` tell ZSS which ports to bind to, but also where the app-server can find ZSS. The values `agent.host` is used to tell app-server where to find ZSS as well, though `agent.https.ipAddresses` and `agent.http.ipAddresses` tell ZSS which addresses to bind to. For addresses, at this time only the first value of that array is used, and it may either be a hostname or an ipv4 address. +ZSS is configured by the same Zowe YAML file used by the App server, within the `components.zss` section of the file. The [ZSS schema for components.zss be found here](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json). More information about the configuration can be found [In its README](https://github.com/zowe/zss/#quick-run-how-to-start-zss). -Example of the agent body: -``` - agent: - host: localhost - https: - ipAddresses: 0.0.0.0 - port: 7557 - -``` +### Connecting ZSS to App Server +The App Server can connect to ZSS either directly or through the API Mediation Layer Gateway when that is running. +The connection information is stored within the object `components.app-server.agent`, which describes whether the Gateway is involved, or if not, on which host and port can ZSS be found. For more information, see the [agent section of the schema](https://github.com/zowe/zlux-app-server/blob/c22105381e129bd999c47e838b424679eba26aa6/schemas/app-server-config.json#L262) From 88e9ca6cb9fe6b3db07595dc669e4b5c7f7bdaa0 Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Wed, 8 Nov 2023 06:22:53 -0500 Subject: [PATCH 02/67] Update mvd-logutility.md link to mvd-server-config.md Signed-off-by: 1000TurquoisePogs --- docs/extend/extend-desktop/mvd-logutility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/extend-desktop/mvd-logutility.md b/docs/extend/extend-desktop/mvd-logutility.md index 82f6a9bcc0..babe67e508 100644 --- a/docs/extend/extend-desktop/mvd-logutility.md +++ b/docs/extend/extend-desktop/mvd-logutility.md @@ -124,7 +124,7 @@ The application plug-in framework provides ways to specify what component logger #### Server startup logging configuration -[The server configuration file](https://github.com/zowe/zlux/wiki/Configuration-for-zLUX-App-Server-&-ZSS) allows for specification of default log levels, as a top-level attribute `logLevel`, which takes key-value pairs where the key is a regex pattern for component IDs, and the value is an integer for the log levels. +[The server configuration file](mvd-server-config.md) allows for specification of default log levels, as a top-level attribute `logLevel`, which takes key-value pairs where the key is a regex pattern for component IDs, and the value is an integer for the log levels. For example: ``` From 9e73f2a3ab331e5f940619ea5da6dc45b588d0e5 Mon Sep 17 00:00:00 2001 From: anaxceron Date: Fri, 12 Jan 2024 15:06:36 -0500 Subject: [PATCH 03/67] fixed punctuation, style, formatting Signed-off-by: anaxceron --- docs/extend/extend-desktop/mvd-logutility.md | 29 ++----- .../extend-desktop/mvd-server-config.md | 84 ++++++++++++------- 2 files changed, 63 insertions(+), 50 deletions(-) diff --git a/docs/extend/extend-desktop/mvd-logutility.md b/docs/extend/extend-desktop/mvd-logutility.md index babe67e508..64c0dd327c 100644 --- a/docs/extend/extend-desktop/mvd-logutility.md +++ b/docs/extend/extend-desktop/mvd-logutility.md @@ -2,24 +2,6 @@ The `zlux-shared` repository provides a logging utility for use by dataservices and web content for an application plug-in. -1. [Logging Objects](#logging-objects) -1. [Logger IDs](#logger-ids) -1. [Accessing Logger Objects](#accessing-logger-objects) - 1. [Logger](#logger) - 1. [App Server](#app-server) - 1. [Web](#web) - 1. [Component Logger](#component-logger) - 1. [App Server](#app-server-1) - 1. [Web](#web-1) -1. [Logger API](#logger-api) -1. [Component Logger API](#component-logger-api) -1. [Log Levels](#log-levels) -1. [Logging Verbosity](#logging-verbosity) - 1. [Configuring Logging Verbosity](#configuring-logging-verbosity) - 1. [Server Startup Logging Configuration](#server-startup-logging-configuration) -1. [Using log message IDs](#using-log-message-ids) - - ## Logging objects The logging utility is based on the following objects: @@ -58,7 +40,6 @@ Component loggers are created from the core logger object, but when working with See **Router Dataservice Context** in the topic [Dataservices](mvd-dataservices.md). - ## Logger API The following constants and functions are available on the central logging object. @@ -106,8 +87,11 @@ An enum, `LogLevel`, exists for specifying the verbosity level of a logger. The | FINER | 4 | TRACE | 5 -**Note:** The default log level for a logger is **INFO**. +:::note + +The default log level for a logger is **INFO**. +::: ## Logging verbosity @@ -127,6 +111,7 @@ The application plug-in framework provides ways to specify what component logger [The server configuration file](mvd-server-config.md) allows for specification of default log levels, as a top-level attribute `logLevel`, which takes key-value pairs where the key is a regex pattern for component IDs, and the value is an integer for the log levels. For example: + ``` "logLevel": { "com.rs.configjs.data.access": 2, @@ -139,9 +124,11 @@ For example: //"_unp.dsauth": 2 }, ``` + For more information about the server configuration file, see [Zowe Application Framework (zLUX) configuration](../../user-guide/mvd-configuration#configuration-file). ## Using log message IDs + To make technical support for your application easier, create IDs for common log messages and use substitution to generate them. When you use IDs, people fielding support calls can identify and solve problems more quickly. IDs are particularly helpful if your application is translated, because it avoids users having to explain problems using language that the tech support person might not understand. To use log message IDs, take the following steps: @@ -179,7 +166,7 @@ To use log message IDs, take the following steps: ``` DATE TIME:TIME:TIME.TIME username INFO (org.zowe.app.name,:) A001 - Приложение создано. ``` - + ### Message ID logging examples Server core: https://github.com/zowe/zlux-server-framework/blob/v2.x/master/plugins/config/lib/assets/i18n/log/messages_en.json diff --git a/docs/extend/extend-desktop/mvd-server-config.md b/docs/extend/extend-desktop/mvd-server-config.md index 65e2ddb774..03b8ebca59 100644 --- a/docs/extend/extend-desktop/mvd-server-config.md +++ b/docs/extend/extend-desktop/mvd-server-config.md @@ -1,17 +1,24 @@ The Zowe's App Server and ZSS rely on many required or optional parameters to run, which includes setting up networking, deployment directories, plugin locations, and more. +# Configuration file -# Configuration File The servers use a YAML file for configuration. The [global schema](https://github.com/zowe/zowe-install-packaging/blob/v2.x/staging/schemas/zowe-yaml-schema.json) describes the parts of configuration that are common between servers. -The App Server specifically is configured by the `components.app-server` section of the YAML, and that section follows [this App-server schema](https://github.com/zowe/zlux-app-server/blob/v2.x/staging/schemas/app-server-config.json) -ZSS is instead configured by the `components.zss` section, following [the ZSS schema](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json) + +The App Server specifically is configured by the `components.app-server` section of the YAML, and that section follows [this App-server schema](https://github.com/zowe/zlux-app-server/blob/v2.x/staging/schemas/app-server-config.json). + +ZSS is instead configured by the `components.zss` section, following [the ZSS schema](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json). + The App server can additionally use CLI arguments or environment variables to override the YAML file. # Environment variables (app-server only) + CLI arguments take precedence over the configuration file, but are overridden by the CLI arguments. -The format is `ZWED_key=value`, where "ZWED_" is a prefix for any configuration object. +The format is `ZWED_key=value`, where `WED_` is a prefix for any configuration object. + The attributes specified will be put within the `components.app-server` subsection of the Zowe configuration. + The key maps to a JSON object attribute, so to set the value of a nested object, such as the https configuration, you need multiple values. + For example: ``` node: @@ -39,27 +46,31 @@ ZWED_logLevels_org____zowe____terminal____tn3270_x2e_x2a:5 ``` **The key names are syntax sensitive.** -* They are case-sensitive -* All ascii characters except " are allowed in the object attribute names. - * An encoding scheme is used for many symbols because environment variables can only have names with the characters A-Z, a-z, 0-9, `_`, `.`, and `-` - * The scheme is _x followed by 2 hex numbers will be converted to the corresponding ASCII character, such as _x41 mapping to `A` -* _ is used as the object separator, so an escape sequence is used if `_` is actually needed for the key. - * Single leading and trailing _ are treated as literal `_` - * __ will be maps to literal `_` - * ___ maps to literal `-` - * ____ maps to literal `.` +* They are case-sensitive. +* All ASCII characters except `"` are allowed in the object attribute names. + * An encoding scheme is used for many symbols because environment variables can only have names with the characters `A`-`Z`, `a`-`z`, `0`-`9`, `_`, `.`, and `-`. + * The scheme is _x followed by 2 hex numbers will be converted to the corresponding ASCII character, such as _x41 mapping to `A`. +* `_` is used as the object separator, so an escape sequence is used if `_` is actually needed for the key. + * Single leading and trailing _ are treated as literal `_`. + * `__` will be maps to literal `_` + * `___` maps to literal `-` + * `____` maps to literal `.` **The types of the values are syntax-sensitive.** * Numbers are treated as numbers, not strings. -* false & true are treated as boolean. -* commas are for arrays. An array of length 1 has a comma at the end -* strings can have quotes, but otherwise everything that isnt an array, boolean, or number is a string -* objects are never values. They are the keys. +* `false` and `true` are treated as boolean. +* Commas are for arrays. An array of length 1 has a comma at the end. +* Strings can have quotes, but otherwise everything that is not an array, boolean, or number is a string. +* Objects are never values, they are the keys. # CLI arguments (app-server only) + CLI arguments take precedence over environment variable and configuration files. + The format is `--key=value` and the attributes specified will be put within the `components.app-server` subsection of the Zowe configuration. + The key maps to a YAML object attribute, so to set the value of a nested object, such as the https configuration, you need multiple period-separated values. + For example: ``` node: @@ -79,24 +90,30 @@ node.https.keys="../defaults/serverConfig/server.key" node.https.certificates="../defaults/serverConfig/server.cert" ``` -**NOTE: ZSS does not support CLI arguments** +:::note + +ZSS does not support CLI arguments. + +::: **The key names are case-sensitive.** **The types of the values are syntax-sensitive.** * Numbers are treated as numbers, not strings. -* false & true are treated as boolean. -* commas are for arrays. An array of length 1 has a comma at the end -* strings can have quotes, but otherwise everything that isnt an array, boolean, or number is a string -* objects are never values. They are the keys. - +* `false` and `true` are treated as boolean. +* Commas are for arrays. An array of length 1 has a comma at the end. +* Strings can have quotes, but otherwise everything that is not an array, boolean, or number is a string. +* Objects are never values, they are the keys. # Parameter Details + Below is some more detail on certain parameters than can be covered within the json-schema. ## Configuration Directories + When running, the App Server will access the server's settings and read/modify the contents of its resource storage. -All of this data is stored within a heirarchy of a few folders, which is correspond to scopes: + +All of this data is stored within a hierarchy of a few folders, which is correspond to scopes: - Product: The contents of this folder are not meant to be modified, but used as defaults for a product. - Site: The contents of this folder are intended to be shared across multiple App Server instances, perhaps on a network drive. - Instance: This folder represents the broadest scope of data within the given App Server instance. @@ -106,25 +123,31 @@ All of this data is stored within a heirarchy of a few folders, which is corresp These directories dictate where the [Configuration Dataservice](https://github.com/zowe/zlux/wiki/Configuration-Dataservice) will store content. ### Directories example + ``` "productDir":"../defaults", "siteDir":"/home/myuser/.zowe/workspace/app-server/site", "instanceDir":"/home/myuser/.zowe/workspace/app-server", "groupsDir":"/home/myuser/.zowe/workspace/app-server/groups", "usersDir":"/home/myuser/.zowe/workspace/app-server/users", - ``` - ## App configuration + This section does not cover any dynamic runtime inclusion of Apps, but rather Apps defined in advance. + In the configuration file, a directory can be specified which contains JSON files which tell the server what App is to be included and where to find it on disk. The backend of these Apps use the Server's Plugin structure, so much of the server-side references to Apps use the term Plugin. To include Apps, be sure to define the location of the Plugins directory in the configuration file, via the top-level attribute *pluginsDir* -**NOTE: In this example, the directory for these JSON files is [/defaults/plugins](https://github.com/zowe/zlux-app-server/tree/v2.x/master/defaults/plugins). Yet, in order to separate configuration files from runtime files, the App Server will initialize by copying the contents of this folder into the defined instance directory, of which the default is ~/.zowe/workspace/app-server. So, the example configuration file uses the latter directory.** +:::note + +In this example, the directory for these JSON files is [/defaults/plugins](https://github.com/zowe/zlux-app-server/tree/v2.x/master/defaults/plugins). Yet, in order to separate configuration files from runtime files, the App Server will initialize by copying the contents of this folder into the defined instance directory, of which the default is ~/.zowe/workspace/app-server. So, the example configuration file uses the latter directory. + +::: + +### Plug-ins directory example -### Plugins directory example ``` // All paths relative to zlux-app-server/lib // In real installations, these values will be configured during the install. @@ -137,8 +160,11 @@ To include Apps, be sure to define the location of the Plugins directory in the For more information, see [Logging Utility](mvd-logutility.md). ## ZSS Configuration -ZSS is configured by the same Zowe YAML file used by the App server, within the `components.zss` section of the file. The [ZSS schema for components.zss be found here](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json). More information about the configuration can be found [In its README](https://github.com/zowe/zss/#quick-run-how-to-start-zss). + +ZSS is configured by the same Zowe YAML file used by the App server, within the `components.zss` section of the file. The [ZSS schema for components.zss be found here](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json). More information about the configuration can be found in its [README file](https://github.com/zowe/zss/#quick-run-how-to-start-zss). ### Connecting ZSS to App Server + The App Server can connect to ZSS either directly or through the API Mediation Layer Gateway when that is running. + The connection information is stored within the object `components.app-server.agent`, which describes whether the Gateway is involved, or if not, on which host and port can ZSS be found. For more information, see the [agent section of the schema](https://github.com/zowe/zlux-app-server/blob/c22105381e129bd999c47e838b424679eba26aa6/schemas/app-server-config.json#L262) From 3049da6b885ae285e3bc50b97453eb17f6e59e5c Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Tue, 26 Mar 2024 10:10:02 -0400 Subject: [PATCH 04/67] Update sidebars.js Signed-off-by: 1000TurquoisePogs --- sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/sidebars.js b/sidebars.js index 5385cfb121..e050e20aba 100644 --- a/sidebars.js +++ b/sidebars.js @@ -722,6 +722,7 @@ module.exports = { type: "category", label: "Developing for Zowe Application Framework", items: [ + "extend/extend-desktop/mvd-server-config", "extend/extend-desktop/mvd-extendingzlux", "extend/extend-desktop/mvd-plugindefandstruct", "extend/extend-desktop/mvd-buildingplugins", From de3a5553829a04dd59ed1d882202bd41dde42b44 Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Fri, 27 Sep 2024 15:34:20 +0200 Subject: [PATCH 05/67] Update mvd-server-config.md with title and headers Signed-off-by: 1000TurquoisePogs --- .../extend-desktop/mvd-server-config.md | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/extend/extend-desktop/mvd-server-config.md b/docs/extend/extend-desktop/mvd-server-config.md index 8f385cd7f2..a3986037b3 100644 --- a/docs/extend/extend-desktop/mvd-server-config.md +++ b/docs/extend/extend-desktop/mvd-server-config.md @@ -1,6 +1,8 @@ +# Advanced Server Configuration + The Zowe's App Server and ZSS rely on many required or optional parameters to run, which includes setting up networking, deployment directories, plugin locations, and more. -# Configuration file +## Configuration file The servers use a YAML file for configuration. The [global schema](https://github.com/zowe/zowe-install-packaging/blob/v2.x/staging/schemas/zowe-yaml-schema.json) describes the parts of configuration that are common between servers. @@ -10,7 +12,7 @@ ZSS is instead configured by the `components.zss` section, following [the ZSS sc The App server can additionally use CLI arguments or environment variables to override the YAML file. -# Environment variables (app-server only) +## Environment variables (app-server only) CLI arguments take precedence over the configuration file, but are overridden by the CLI arguments. The format is `ZWED_key=value`, where `WED_` is a prefix for any configuration object. @@ -64,7 +66,7 @@ ZWED_logLevels_org____zowe____terminal____tn3270_x2e_x2a:5 * Objects are never values, they are the keys. -# CLI arguments (app-server only) +## CLI arguments (app-server only) CLI arguments take precedence over environment variable and configuration files. @@ -106,11 +108,11 @@ ZSS does not support CLI arguments. * Strings can have quotes, but otherwise everything that is not an array, boolean, or number is a string. * Objects are never values, they are the keys. -# Parameter Details +## Parameter Details Below is some more detail on certain parameters than can be covered within the json-schema. -## Configuration Directories +### Configuration Directories When running, the App Server will access the server's settings and read/modify the contents of its resource storage. @@ -123,7 +125,7 @@ All of this data is stored within a hierarchy of a few folders, which is corresp These directories dictate where the [Configuration Dataservice](https://github.com/zowe/zlux/wiki/Configuration-Dataservice) will store content. -### Directories example +#### Directories example ``` "productDir":"../defaults", @@ -133,7 +135,7 @@ These directories dictate where the [Configuration Dataservice](https://github.c "usersDir":"/home/myuser/.zowe/workspace/app-server/users", ``` -## App configuration +### App configuration This section does not cover any dynamic runtime inclusion of Apps, but rather Apps defined in advance. @@ -147,7 +149,7 @@ In this example, the directory for these JSON files is [/defaults/plugins](https ::: -### Plug-ins directory example +#### Plug-ins directory example ``` // All paths relative to zlux-app-server/lib @@ -156,15 +158,15 @@ In this example, the directory for these JSON files is [/defaults/plugins](https "pluginsDir":"../defaults/plugins", ``` -## Logging configuration +### Logging configuration For more information, see [Logging Utility](mvd-logutility.md). -## ZSS Configuration +### ZSS Configuration ZSS is configured by the same Zowe YAML file used by the App server, within the `components.zss` section of the file. The [ZSS schema for components.zss be found here](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json). More information about the configuration can be found in its [README file](https://github.com/zowe/zss/#quick-run-how-to-start-zss). -### Connecting ZSS to App Server +#### Connecting ZSS to App Server The App Server can connect to ZSS either directly or through the API Mediation Layer Gateway when that is running. From eea5467c89310b8ddd90276442ca2e95a9c6d0bc Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Fri, 1 Nov 2024 16:49:19 +0100 Subject: [PATCH 06/67] initial refactor with title change and collapsable ESM commands Signed-off-by: Andrew Jandacek --- docs/user-guide/configure-zos-system.md | 792 +++++++++++++++--------- 1 file changed, 501 insertions(+), 291 deletions(-) diff --git a/docs/user-guide/configure-zos-system.md b/docs/user-guide/configure-zos-system.md index 64ca26a40e..a17526f10a 100644 --- a/docs/user-guide/configure-zos-system.md +++ b/docs/user-guide/configure-zos-system.md @@ -1,10 +1,18 @@ -# Addressing z/OS requirements for Zowe +# Security customization of your z/OS system -As a security administrator it is necessary to configure the z/OS system for Zowe. Review the following article to learn about z/OS prerequisites, and z/OS configuration requirements for specific settings. +As a security administrator configure your z/OS system according to the specific features and functionalities you choose to include in your Zowe installation. Review the following article for specific configuration steps that apply to these features and fuctionalities. :::info Required role: security administrator ::: + +:::note +Before performing configuration steps specific to your use case, ensure that you meet the z/OS system requirements presented in the section _Preparing for installation_. For detailed information, see [Addressing z/OS requirements](./systemrequirements-zos.md). +::: + + of free space for Zowe server components, their keystore, instance configuration files and logs, and third-party plug-ins. +- zFS volume has 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 @@ -25,9 +33,9 @@ Be sure your z/OS system meets the following prerequisites: To deploy Zowe for high availability, a Parallel Sysplex environment is recommended. For more information, see [Configuring Sysplex for high availability](configure-sysplex.md). - ## Settings specific configuration requirements +--> -Configuration of your z/OS system is dependent on the specific Zowe features and functionalities you would like to employ with your Zowe installation. Review the following table to determine which configuration steps are required based on your Zowe use case. + Review the following table to determine which configuration steps are required based on your Zowe use case. | Purpose | Configuration step | | --- | --- | @@ -66,62 +74,85 @@ Define or check the following configurations depending on whether ICSF is alread - Create CKDS, PKDS, TKDS VSAM data sets. - Define and activate the CSFSERV class: - - If you use RACF, issue the following commands: - ``` - RDEFINE CSFSERV profile-name UACC(NONE) - ``` - ``` - PERMIT profile-name CLASS(CSFSERV) ID(tcpip-stackname) ACCESS(READ) - ``` - ``` - PERMIT profile-name CLASS(CSFSERV) ID(userid-list) ... [for - userids IKED, NSSD, and Policy Agent] - ``` - ``` - SETROPTS CLASSACT(CSFSERV) - ``` - ``` - SETROPTS RACLIST(CSFSERV) REFRESH - ``` - - If you use ACF2, issue the following commands (note that `profile-prefix` and `profile-suffix` are user-defined): - ``` - SET CONTROL(GSO) - ``` - ``` - INSERT CLASMAP.CSFSERV RESOURCE(CSFSERV) RSRCTYPE(CSF) - ``` - ``` - F ACF2,REFRESH(CLASMAP) - ``` - ``` - SET RESOURCE(CSF) - ``` - ``` - RECKEY profile-prefix ADD(profile-suffix uid(UID string for tcpip-stackname) SERVICE(READ) ALLOW) - ``` - ``` - RECKEY profile-prefix ADD(profile-suffix uid(UID string for IZUSVR) SERVICE(READ) ALLOW) - ``` - (repeat for userids IKED, NSSD, and Policy Agent) +
- ``` - F ACF2,REBUILD(CSF) - ``` - - If you use Top Secret, issue the following command (note that `profile-prefix` and `profile-suffix` are user defined): - ``` - TSS ADDTO(owner-acid) RESCLASS(CSFSERV) - ``` - ``` - TSS ADD(owner-acid) CSFSERV(profile-prefix.) - ``` - ``` - TSS PERMIT(tcpip-stackname) CSFSERV(profile-prefix.profile-suffix) ACCESS(READ) - ``` - ``` - TSS PERMIT(user-acid) CSFSERV(profile-prefix.profile-suffix) ACCESS(READ) - ``` - (repeat for user-acids IKED, NSSD, and Policy Agent) + For RACF, click here for command details. + +If you use RACF, issue the following commands: +``` +RDEFINE CSFSERV profile-name UACC(NONE) +``` +``` +PERMIT profile-name CLASS(CSFSERV) ID(tcpip-stackname) ACCESS(READ) +``` +``` +PERMIT profile-name CLASS(CSFSERV) ID(userid-list) ... [for +userids IKED, NSSD, and Policy Agent] +``` +``` +SETROPTS CLASSACT(CSFSERV) +``` +``` +SETROPTS RACLIST(CSFSERV) REFRESH +``` + +
+ +
+ + For ACF2, click here for command details. + + +If you use ACF2, issue the following commands (note that `profile-prefix` and `profile-suffix` are user-defined): + +``` +SET CONTROL(GSO) +``` +``` +INSERT CLASMAP.CSFSERV RESOURCE(CSFSERV) RSRCTYPE(CSF) +``` +``` +F ACF2,REFRESH(CLASMAP) +``` +``` +SET RESOURCE(CSF) +``` +``` +RECKEY profile-prefix ADD(profile-suffix uid(UID string for tcpip-stackname) SERVICE(READ) ALLOW) +``` +``` +RECKEY profile-prefix ADD(profile-suffix uid(UID string for IZUSVR) SERVICE(READ) ALLOW) +``` +(repeat for userids IKED, NSSD, and Policy Agent) + +``` +F ACF2,REBUILD(CSF) +``` + +
+ +
+ + For Top Secret, click here for command details. + +If you use Top Secret, issue the following command (note that `profile-prefix` and `profile-suffix` are user defined): + +``` +TSS ADDTO(owner-acid) RESCLASS(CSFSERV) +``` +``` +TSS ADD(owner-acid) CSFSERV(profile-prefix.) +``` +``` +TSS PERMIT(tcpip-stackname) CSFSERV(profile-prefix.profile-suffix) ACCESS(READ) +``` +``` +TSS PERMIT(user-acid) CSFSERV(profile-prefix.profile-suffix) ACCESS(READ) +``` +(repeat for user-acids IKED, NSSD, and Policy Agent) + +
:::note Notes - Determine whether you want SAF authorization checks against `CSFSERV` and set `CSF.CSFSERV.AUTH.CSFRNG.DISABLE` accordingly. @@ -138,149 +169,212 @@ To enable impersonation, you must grant the user ID `ZWESVUSR` associated with t 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: - ``` - RLIST FACILITY BPX.SERVER AUTHUSER - ``` - ``` - RLIST FACILITY BPX.DAEMON AUTHUSER - ``` -- If you use Top Secret, issue the following commands: - ``` - TSS WHOHAS IBMFAC(BPX.SERVER) - ``` - ``` - TSS WHOHAS IBMFAC(BPX.DAEMON) - ``` -- If you use ACF2, issue the following commands: - ``` - SET RESOURCE(FAC) - ``` - ``` - LIST BPX - ``` +
+ + For RACF, click here for command details. + + +If you use RACF, issue the following commands: +``` +RLIST FACILITY BPX.SERVER AUTHUSER +``` +``` +RLIST FACILITY BPX.DAEMON AUTHUSER +``` + +
+ +
+ +For Top Secret, click here for command details. + + +If you use Top Secret, issue the following commands: +``` +TSS WHOHAS IBMFAC(BPX.SERVER) +``` +``` +TSS WHOHAS IBMFAC(BPX.DAEMON) +``` + +
-If the user `ZWESVUSR` who runs the Zowe server started task does not have UPDATE access to both profiles follow the instructions below. +
+ +For ACF2, click here for command details. + -- If you use RACF, complete the following steps: +If you use ACF2, issue the following commands: +``` +SET RESOURCE(FAC) +``` +``` +LIST BPX +``` + +
+ +If the user `ZWESVUSR` who runs the Zowe server started task does not have UPDATE access to both profiles follow the instructions according to your ESM. + +
+ +For RACF, click here for procedure details. + + +If you use RACF, complete the following steps: - 1. Activate and RACLIST the FACILITY class. This may have already been done on the z/OS environment if another z/OS server has been previously configured to take advantage of the ability to change its security environment, such as the FTPD daemon that is included with z/OS Communications Server TCP/IP services. - ``` - SETROPTS GENERIC(FACILITY) - SETROPTS CLASSACT(FACILITY) RACLIST(FACILITY) - ``` - 2. Define the impersonation profiles. This may have already been done on behalf of another server such as the FTPD daemon. - ``` - RDEFINE FACILITY BPX.SERVER UACC(NONE) - ``` - ``` - RDEFINE FACILITY BPX.DAEMON UACC(NONE) - ``` - 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.DAEMON CLASS(FACILITY) ID() ACCESS(UPDATE) - ``` - where `` is `ZWESVUSR` unless a different user ID is being used for the z/OS environment. - - /* Activate these changes */ - - ``` - SETROPTS RACLIST(FACILITY) REFRESH - ``` - 4. Issue the following commands to check whether permission has been successfully granted: - ``` - RLIST FACILITY BPX.SERVER AUTHUSER - ``` - ``` - RLIST FACILITY BPX.DAEMON AUTHUSER - ``` -- If you use Top Secret, complete the following steps: +1. Activate and RACLIST the FACILITY class. This may have already been done on the z/OS environment if another z/OS server has been previously configured to take advantage of the ability to change its security environment, such as the FTPD daemon that is included with z/OS Communications Server TCP/IP services. +``` +SETROPTS GENERIC(FACILITY) +SETROPTS CLASSACT(FACILITY) RACLIST(FACILITY) +``` +2. Define the impersonation profiles. This may have already been done on behalf of another server such as the FTPD daemon. +``` +RDEFINE FACILITY BPX.SERVER UACC(NONE) +``` +``` +RDEFINE FACILITY BPX.DAEMON UACC(NONE) +``` +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.DAEMON CLASS(FACILITY) ID() ACCESS(UPDATE) +``` +where: + +* `` is `ZWESVUSR` unless a different user ID is being used for the z/OS environment. + +/* Activate these changes */ + +``` +SETROPTS RACLIST(FACILITY) REFRESH +``` +4. Issue the following commands to check whether permission has been successfully granted: +``` +RLIST FACILITY BPX.SERVER AUTHUSER +``` +``` +RLIST FACILITY BPX.DAEMON AUTHUSER +``` + +
+ +
+ For Top Secret, click here for procedure details. + + +If you use Top Secret, complete the following steps: - 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.DAEMON) ACCESS(UPDATE) - ``` - 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) - ``` - ``` - TSS WHOHAS IBMFAC(BPX.DAEMON) - ``` -- If you use ACF2, complete the following steps: - 1. Define the BPX Resource and access for ``. - ``` - SET RESOURCE(FAC) - ``` - ``` - RECKEY BPX ADD(SERVER 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. - ``` - F ACF2,REBUILD(FAC) - ``` - 2. Issue the following commands and review the output to check whether permission has been successfully granted: - ``` - SET RESOURCE(FAC) - ``` - ``` - LIST BPX - ``` +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.DAEMON) ACCESS(UPDATE) +``` +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) +``` +``` +TSS WHOHAS IBMFAC(BPX.DAEMON) +``` +
+ +
+ +For ACF2, click here for procedure details. + + +If you use ACF2, complete the following steps: +1. Define the BPX Resource and access for ``. +``` +SET RESOURCE(FAC) +``` +``` +RECKEY BPX ADD(SERVER 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. +``` +F ACF2,REBUILD(FAC) +``` +2. Issue the following commands and review the output to check whether permission has been successfully granted: +``` +SET RESOURCE(FAC) +``` +``` +LIST BPX +``` +
You must also grant READ access to the OMVSAPPL profile in the APPL class to the Zowe STC user as well as **all other Zowe users** using various Zowe features. Skip the following steps when the OMVSAPPL profile is not defined in your environment. -- If you use RACF, complete the following steps: +
+For RACF, click here for procedure details. + - 1. Check if you already have the required access defined as part of the environment configuration. Skip the following steps if access is already granted. - ``` - RLIST APPL OMVSAPPL AUTHUSER - ``` +If you use RACF, complete the following steps: - 2. Issue the following commands and review the output to check if permission has been successfully granted: - ``` - PERMIT OMVSAPPL CLASS(APPL) ID() ACCESS(READ) - SETROPTS RACLIST(APPL) REFRESH - ``` +1. Check if you already have the required access defined as part of the environment configuration. Skip the following steps if access is already granted. +``` +RLIST APPL OMVSAPPL AUTHUSER +``` -- If you use Top Secret, complete the following steps: +2. Issue the following commands and review the output to check if permission has been successfully granted: +``` +PERMIT OMVSAPPL CLASS(APPL) ID() ACCESS(READ) +SETROPTS RACLIST(APPL) REFRESH +``` - 1. Check if you already have the required access as part of the environment configuration. Skip the following steps if access is already granted. - ``` - TSS WHOHAS APPL(OMVSAPPL) - ``` +
- 2. Issue the following commands and review the output to check if permission has been successfully granted: - ``` - TSS PERMIT() APPL(OMVSAPPL) - ``` +
+For Top Secret, click here for procedure details. + -- If you use ACF2, complete the following steps: +If you use Top Secret, complete the following steps: - 1. Check if you already have the required access defined as part of the environment configuration. Skip the following steps if access is already granted. - ``` - SET RESOURCE(APL) - LIST OMVSAAPL - ``` +1. Check if you already have the required access as part of the environment configuration. Skip the following steps if access is already granted. +``` +TSS WHOHAS APPL(OMVSAPPL) +``` - 2. Issue the following commands and review the output to check if permission has been successfully granted: - ``` - SET RESOURCE(APL) - RECKEY OMVSAPPL ADD(SERVICE(READ) ROLE() ALLOW) - F ACF2,REBUILD(APL) - ``` +2. Issue the following commands and review the output to check if permission has been successfully granted: +``` +TSS PERMIT() APPL(OMVSAPPL) +``` +
+ +
+For ACF2, click here for procedure details. + + +If you use ACF2, complete the following steps: + +1. Check if you already have the required access defined as part of the environment configuration. Skip the following steps if access is already granted. +``` +SET RESOURCE(APL) +LIST OMVSAAPL +``` + +2. Issue the following commands and review the output to check if permission has been successfully granted: +``` +SET RESOURCE(APL) +RECKEY OMVSAPPL ADD(SERVICE(READ) ROLE() ALLOW) +F ACF2,REBUILD(APL) +``` +
### Configure address space job naming @@ -391,25 +485,46 @@ If you have run `ZWESECUR`, you do not need to perform the steps described in th 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) - ``` +
+ +For RACF, click here for command details. + -- If you use ACF2, issue the following commands: +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) +``` - ``` - SET CONTROL(GSO) - INSERT STC.ZWESLSTC LOGONID(ZWESVUSR) GROUP(ZWEADMIN) STCID(ZWESLSTC) - F ACF2,REFRESH(STC) - ``` +
-- If you use Top Secret, issue the following commands: +
+ +For ACF2, click here for command details. + - ``` - TSS ADDTO(STC) PROCNAME(ZWESLSTC) ACID(ZWESVUSR) - ``` +If you use ACF2, issue the following commands: + +``` +SET CONTROL(GSO) +INSERT STC.ZWESLSTC LOGONID(ZWESVUSR) GROUP(ZWEADMIN) STCID(ZWESLSTC) +F ACF2,REFRESH(STC) +``` + +
+ +
+ +For Top Secret, click here for command details. + + +If you use Top Secret, issue the following commands: + +``` +TSS ADDTO(STC) PROCNAME(ZWESLSTC) ACID(ZWESVUSR) +``` + +
### Configure the cross memory server for SAF @@ -426,60 +541,83 @@ If you have not run `ZWESECUR` and are configuring your z/OS environment manuall 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 Zowe server under the `ZWESVUSR` user. +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: +
- - To see the current class settings, use: - ``` - SETROPTS LIST - ``` - - To define and activate the FACILITY class, use: - ``` - SETROPTS GENERIC(FACILITY) - SETROPTS CLASSACT(FACILITY) - ``` - - To RACLIST the FACILITY class, use: - ``` - SETROPTS RACLIST(FACILITY) - ``` - - To define the `ZWES.IS` profile in the FACILITY class and grant Zowe's started task userid READ access, issue the following commands: - ``` - RDEFINE FACILITY ZWES.IS UACC(NONE) - ``` - ``` - PERMIT ZWES.IS CLASS(FACILITY) ID() ACCESS(READ) - ``` - where `` is the user ID `ZWESVUSR` under which the Zowe server started task runs. - ``` - SETROPTS RACLIST(FACILITY) REFRESH - ``` - - To check whether the permission has been successfully granted, issue the following command: - ``` - RLIST FACILITY ZWES.IS AUTHUSER - ``` - This shows the user IDs who have access to the `ZWES.IS` class, which should include Zowe's started task user ID with READ access. + +For RACF, click here for command details. + -- If you use ACF2, issue the following commands: +If you use RACF, issue the following commands: +- To see the current class settings, use: ``` - SET RESOURCE(FAC) + SETROPTS LIST + ``` +- To define and activate the FACILITY class, use: ``` + SETROPTS GENERIC(FACILITY) + SETROPTS CLASSACT(FACILITY) ``` - RECKEY ZWES ADD(IS ROLE(IZUSVR) SERVICE(READ) ALLOW) +- To RACLIST the FACILITY class, use: ``` + SETROPTS RACLIST(FACILITY) ``` - F ACF2,REBUILD(FAC) +- To define the `ZWES.IS` profile in the FACILITY class and grant Zowe's started task userid READ access, issue the following commands: ``` - -- If you use Top Secret, issue the following commands, where `owner-acid` can be IZUSVR or a different ACID: - + RDEFINE FACILITY ZWES.IS UACC(NONE) ``` - TSS ADD(`owner-acid`) IBMFAC(ZWES.) ``` + PERMIT ZWES.IS CLASS(FACILITY) ID() ACCESS(READ) + ``` + where: + * `` is the user ID `ZWESVUSR` under which the Zowe server started task runs. ``` - TSS PERMIT(ZWESVUSR) IBMFAC(ZWES.IS) ACCESS(READ) + SETROPTS RACLIST(FACILITY) REFRESH + ``` +- To check whether the permission has been successfully granted, issue the following command: + ``` + RLIST FACILITY ZWES.IS AUTHUSER ``` + This shows the user IDs who have access to the `ZWES.IS` class, which should include Zowe's started task user ID with READ access. + +
+ +
+ +For ACF2, click here for command details. + + +If you use ACF2, issue the following commands: + +``` +SET RESOURCE(FAC) +``` +``` +RECKEY ZWES ADD(IS ROLE(IZUSVR) SERVICE(READ) ALLOW) +``` +``` +F ACF2,REBUILD(FAC) +``` + +
+ +
+ +For Top Secret, click here for command details. + + +If you use Top Secret, issue the following commands, where `owner-acid` can be IZUSVR or a different ACID: + +``` +TSS ADD(`owner-acid`) IBMFAC(ZWES.) +``` +``` +TSS PERMIT(ZWESVUSR) IBMFAC(ZWES.IS) ACCESS(READ) +``` + +
:::note Notes - The cross memory server treats "no decision" style SAF return codes as failures. If there is no covering profile for the `ZWES.IS` resource in the FACILITY class, the request will be denied. @@ -491,7 +629,10 @@ To do this, issue the following commands that are also included in the `ZWESECUR This security configuration is necessary for API ML to be able to map client certificate to a z/OS identity. A user running API Gateway must have read access to the SAF resource `IRR.RUSERMAP` in the `FACILITY` class. To set up this security configuration, submit the `ZWESECUR` JCL member. For users upgrading from version 1.18 and lower use the following configuration steps. -#### Using RACF +
+ +For RACF, click here for procedure details. + If you use RACF, verify and update permission in the `FACILITY` class. @@ -511,8 +652,12 @@ If you use RACF, verify and update permission in the `FACILITY` class. ``` SETROPTS RACLIST(FACILITY) REFRESH ``` +
-#### Using ACF2 +
+ +For ACF2, click here for procedure details. + If you use ACF2, verify and update permission in the `FACILITY` class. @@ -534,7 +679,12 @@ If you use ACF2, verify and update permission in the `FACILITY` class. F ACF2,REBUILD(FAC) ``` -#### Using TSS +
+ +
+ +For Top Secret, click here for procedure details. + If you use TSS, verify and update permission in `FACILITY` class. @@ -549,12 +699,17 @@ If you use TSS, verify and update permission in `FACILITY` class. TSS PER(ZWESVUSR) IBMFAC(IRR.RUSERMAP) ACCESS(READ) ``` +
+ ### Configure main Zowe server to use distributed identity mapping This security configuration is necessary for API ML to be able to map the association between a z/OS user ID and a distributed user identity. A user running the API Gateway must have read access to the SAF resource `IRR.IDIDMAP.QUERY` in the `FACILITY` class. To set up this security configuration, submit the `ZWESECUR` JCL member. For users upgrading from version 1.28 and lower, use the following configuration steps. -#### Using RACF +
+ +For RACF, click here for procedure details. + If you use RACF, verify and update permission in the `FACILITY` class. @@ -582,7 +737,12 @@ If you use RACF, verify and update permission in the `FACILITY` class. SETROPTS RACLIST(FACILITY) REFRESH ``` -#### Using ACF2 +
+ +
+ +For ACF2, click here for procedure details. + If you use ACF2, verify and update permission in the `FACILITY` class. @@ -604,7 +764,12 @@ If you use ACF2, verify and update permission in the `FACILITY` class. F ACF2,REBUILD(FAC) ``` -#### Using TSS +
+ +
+ +For Top Secret, click here for procedure details. + If you use TSS, verify and update permission in `FACILITY` class. @@ -620,11 +785,13 @@ If you use TSS, verify and update permission in `FACILITY` class. TSS PER(ZWESVUSR) IBMFAC(IRR.IDIDMAP.QUERY) ACCESS(READ) ``` +
+ ### Configure signed SAF Identity tokens (IDT) This section provides a brief description of how to configure SAF Identity tokens on z/OS so that they can be used by Zowe components like zss or API Mediation layer ([Implement a new SAF IDT provider](../extend/extend-apiml/implement-new-saf-provider.md)) -Follow these general steps: +**Follow these general steps:** 1. Create PKCS#11 token 2. Generate a secret key for the PKCS#11 token (you can use the sample program ZWESECKG in the SZWESAMP dataset) @@ -644,54 +811,97 @@ To set up this security configuration, submit the `ZWESECUR` JCL member. For use To check whether you already have the auditing profile defined, issue the following command and review the output to confirm that the profile exists and that the user `ZWESVUSR` who runs the `ZWESLSTC` started task has READ access to this profile. -- If you use RACF, issue the following command: - ``` - RLIST FACILITY IRR.RAUDITX AUTHUSER - ``` -- If you use Top Secret, issue the following command: - ``` - TSS WHOHAS IBMFAC(IRR.RAUDITX) - ``` -- If you use ACF2, issue the following commands: +
+ +For RACF, click here for command details. + + +If you use RACF, issue the following command: +``` +RLIST FACILITY IRR.RAUDITX AUTHUSER +``` + +
+ +
+ +For Top Secret, click here for command details. + + +If you use Top Secret, issue the following command: +``` +TSS WHOHAS IBMFAC(IRR.RAUDITX) +``` + +
+ +
+ +For ACF2, click here for command details. + + +If you use ACF2, issue the following commands: +``` +SET RESOURCE(FAC) +``` +``` +LIST LIKE(IRR-) +``` +
+ +If the user `ZWESVUSR` who runs the `ZWESLSTC` started task does not have READ access to this profile, follow the procedure that corresponds to your ESM. + +
+ +For RACF, click here for procedure details. + + +If you use RACF, update permission in the `FACILITY` class. + +**Follow these steps:** + +1. Add user `ZWESVUSR` permission to `READ`. ``` - SET RESOURCE(FAC) + PERMIT IRR.RAUDITX CLASS(FACILITY) ACCESS(READ) ID(ZWESVUSR) ``` +2. Activate changes. ``` - LIST LIKE(IRR-) + SETROPTS RACLIST(FACILITY) REFRESH ``` +
+ +
+ +For Top Secret, click here for procedure details. + + +If you use Top Secret, add user `ZWESVUSR` permission to READ. Issue the following command: +``` +TSS PER(ZWESVUSR) IBMFAC(IRR.RAUDITX) ACCESS(READ) +``` + +
+ +
+ +For ACF2, click here for procedure details. + + +If you use ACF2, add user `ZWESVUSR` permission to `READ`. Issue the following commands: +``` +SET RESOURCE(FAC) +``` +``` +RECKEY IRR ADD(RAUDITX ROLE(&STCGRP.) SERVICE(READ) ALLOW) +``` +``` +F ACF2,REBUILD(FAC) +``` + +
-If the user `ZWESVUSR` who runs the `ZWESLSTC` started task does not have READ access to this profile, follow the procedure that corresponds to your ESM: - -- If you use RACF, update permission in the `FACILITY` class. - - **Follow these steps:** - - 1. Add user `ZWESVUSR` permission to `READ`. - ``` - PERMIT IRR.RAUDITX CLASS(FACILITY) ACCESS(READ) ID(ZWESVUSR) - ``` - 2. Activate changes. - ``` - SETROPTS RACLIST(FACILITY) REFRESH - ``` - -- If you use Top Secret, add user `ZWESVUSR` permission to READ. Issue the following command: - ``` - TSS PER(ZWESVUSR) IBMFAC(IRR.RAUDITX) ACCESS(READ) - ``` - -- If you use ACF2, add user `ZWESVUSR` permission to `READ`. Issue the following commands: - ``` - SET RESOURCE(FAC) - ``` - ``` - RECKEY IRR ADD(RAUDITX ROLE(&STCGRP.) SERVICE(READ) ALLOW) - ``` - ``` - F ACF2,REBUILD(FAC) - ``` - For more information about SMF records, see [SMF records](../user-guide/api-mediation/api-mediation-smf.md) in the Using Zowe API Mediation Layer documentation. + ### Multi-Factor Authentication (MFA) Multi-factor authentication is supported for several components, such as the Desktop and API Mediation Layer. From 55335a747bcca0015db10e57125c1649e165f2f1 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 4 Nov 2024 12:25:44 +0100 Subject: [PATCH 07/67] initial component listing for security customization Signed-off-by: Andrew Jandacek --- .../assign-security-permissions-to-users.md | 17 ++++++ docs/user-guide/configure-zos-system.md | 57 ++++++------------- docs/user-guide/systemrequirements-zos.md | 3 + 3 files changed, 37 insertions(+), 40 deletions(-) diff --git a/docs/user-guide/assign-security-permissions-to-users.md b/docs/user-guide/assign-security-permissions-to-users.md index 20323ddaac..1cbd26e142 100644 --- a/docs/user-guide/assign-security-permissions-to-users.md +++ b/docs/user-guide/assign-security-permissions-to-users.md @@ -59,6 +59,23 @@ see [zwe init security](../appendix/zwe_server_command_reference/zwe/init/zwe-in | Cross memory server (ZIS) | FACILITY | `ZWES.IS` | READ | Allow Zowe ZWESLSTC processes to access the Zowe ZIS cross memory server. | This parameter permits the Zowe main server to use ZIS cross memory server. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L329)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L560)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L780) | +## Configuring address space job naming + +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. + +1. To display who is authorized to the profile, issue the following command: +``` +RLIST FACILITY BPX.JOBNAME AUTHUSER +``` + +2. Activate the facility class, permit `BPX.JOBNAME`, and refresh facility class: +``` +SETROPTS CLASSACT(FACILITY) RACLIST(FACILITY) +PERMIT BPX.JOBNAME CLASS(FACILITY) ID(ZWESVUSR) ACCESS(READ) +SETROPTS RACLIST(FACILITY) REFRESH +``` + +For more information, see [Setting up the UNIX-related FACILITY and SURROGAT class profiles](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.bpxb200/fclass.htm) in the "z/OS UNIX System Services" documentation. ## Granting users permission to access z/OSMF diff --git a/docs/user-guide/configure-zos-system.md b/docs/user-guide/configure-zos-system.md index a17526f10a..5d1400ca99 100644 --- a/docs/user-guide/configure-zos-system.md +++ b/docs/user-guide/configure-zos-system.md @@ -1,6 +1,6 @@ # Security customization of your z/OS system -As a security administrator configure your z/OS system according to the specific features and functionalities you choose to include in your Zowe installation. Review the following article for specific configuration steps that apply to these features and fuctionalities. +As a security administrator, configure your z/OS system according to the specific features and functionalities you choose to include in your Zowe installation. Review the following article for specific configuration steps that apply to these features and fuctionalities. :::info Required role: security administrator ::: @@ -37,23 +37,22 @@ Be sure your z/OS system meets the following prerequisites: Review the following table to determine which configuration steps are required based on your Zowe use case. -| Purpose | Configuration step | -| --- | --- | -| Set the names for the different z/OS UNIX address spaces for the Zowe runtime components.
**Important:** This configuration step is required. | [Configure address space job naming](#configure-address-space-job-naming) | -| To use Zowe desktop. This step generates random numbers for zssServer that the Zowe desktop uses. | [Configure an ICSF cryptographic services environment](#configure-an-icsf-cryptographic-services-environment) | -| To allow users to log on to the Zowe desktop through impersonation. | [Configure security environment switching](#configure-security-environment-switching) | -| Required for TSS only. A TSS FACILITY needs to be defined and assigned to the `ZWESLSTC` started task. | [Configure multi-user address space for TSS only](#configure-multi-user-address-space-for-tss-only) | -| Required if you have not run `ZWESECUR` and are manually creating the user ID and groups in your z/OS environment. | [Configure user IDs and groups for the Zowe started tasks](#configure-user-ids-and-groups-for-the-zowe-started-tasks) | -| Required if you have not run `ZWESECUR` and are configuring your z/OS environment manually. This step describes how to configure the started task ZWESLSTC to run under the correct user ID and group. | [Configure ZWESLSTC to run Zowe high availability instances under ZWESVUSR user ID](#configure-zweslstc-to-run-zowe-high-availability-instances-under-zwesvusr-user-id) | -| Required if you have not run `ZWESECUR` and are configuring your z/OS environment manually. This step describes how to configure the cross memory server for SAF to guard against access by non-privileged clients. | [Configure the cross memory server for SAF](#configure-the-cross-memory-server-for-saf) | -| Required for API Mediation Layer to map a client certificate to a z/OS identity. | [Configure main Zowe server to use client certificate identity mapping](#configure-main-zowe-server-to-use-client-certificate-identity-mapping) | -| Required for API ML to map the association between a z/OS user ID and a distributed user identity. | [Configure main Zowe server to use distributed identity mapping](#configure-main-zowe-server-to-use-distributed-identity-mapping) | -| To configure SAF Identity tokens on z/OS so that they can be used by Zowe components like zss or API Mediation Layer. | [Configure signed SAF Identity tokens IDT](#configure-signed-saf-identity-tokens-idt) | -| Required for API Mediation Layer to issue SMF records. | [Configure the main Zowe server to issue SMF records](api-mediation/api-mediation-smf.md#configure-the-main-zowe-server-to-issue-smf-records) | -| To use multi-factor authentication (MFA) | [Multi-Factor Authentication (MFA)](#multi-factor-authentication-mfa) | -| To use Single Sign-On (SSO) | [Single Sign-On (SSO)](#single-sign-on-sso) | -| To use OIDC Authentication with API Mediation Layer | [API Mediation Layer OIDC Authentication](#api-mediation-layer-oidc-authentication) | - +| Purpose | Applicable Zowe Component(s) | Configuration step | +| --- | --- | --- | +| Set the names for the different z/OS UNIX address spaces for the Zowe runtime components.
**Important:** This configuration step is required. | All components | [Configure address space job naming](#configure-address-space-job-naming) | +| To use Zowe desktop. This step generates random numbers for zssServer that the Zowe desktop uses. | Application Framework | [Configure an ICSF cryptographic services environment](#configure-an-icsf-cryptographic-services-environment) | +| To allow users to log on to the Zowe desktop through impersonation. | | [Configure security environment switching](#configure-security-environment-switching) | +| Required for TSS only. A TSS FACILITY needs to be defined and assigned to the `ZWESLSTC` started task. | | [Configure multi-user address space for TSS only](#configure-multi-user-address-space-for-tss-only) | +| Required if you have not run `ZWESECUR` and are manually creating the user ID and groups in your z/OS environment. | | [Configure user IDs and groups for the Zowe started tasks](#configure-user-ids-and-groups-for-the-zowe-started-tasks) | +| Required if you have not run `ZWESECUR` and are configuring your z/OS environment manually. This step describes how to configure the started task ZWESLSTC to run under the correct user ID and group. | | [Configure ZWESLSTC to run Zowe high availability instances under ZWESVUSR user ID](#configure-zweslstc-to-run-zowe-high-availability-instances-under-zwesvusr-user-id) | +| Required if you have not run `ZWESECUR` and are configuring your z/OS environment manually. This step describes how to configure the cross memory server for SAF to guard against access by non-privileged clients. | Application Framework | [Configure the cross memory server for SAF](#configure-the-cross-memory-server-for-saf) | +| Required for API Mediation Layer to map a client certificate to a z/OS identity. | API ML | [Configure main Zowe server to use client certificate identity mapping](#configure-main-zowe-server-to-use-client-certificate-identity-mapping) | +| Required for API ML to map the association between a z/OS user ID and a distributed user identity. | API ML | [Configure main Zowe server to use distributed identity mapping](#configure-main-zowe-server-to-use-distributed-identity-mapping) | +| To configure SAF Identity tokens on z/OS so that they can be used by Zowe components like zss or API Mediation Layer. | | [Configure signed SAF Identity tokens IDT](#configure-signed-saf-identity-tokens-idt) | +| Required for API Mediation Layer to issue SMF records. | API ML | [Configure the main Zowe server to issue SMF records](api-mediation/api-mediation-smf.md#configure-the-main-zowe-server-to-issue-smf-records) | +| To use multi-factor authentication (MFA) | | [Multi-Factor Authentication (MFA)](#multi-factor-authentication-mfa) | +| To use Single Sign-On (SSO) | | [Single Sign-On (SSO)](#single-sign-on-sso) | +| To use OIDC Authentication with API Mediation Layer | API ML | [API Mediation Layer OIDC Authentication](#api-mediation-layer-oidc-authentication) | ### Configure an ICSF cryptographic services environment @@ -376,28 +375,6 @@ F ACF2,REBUILD(APL) ``` -### Configure address space job naming - -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. - -:::note -This procedure may require security administrator authorization. Consult with your security administrator. -::: - -To display who is authorized to the profile, issue the following command: -``` -RLIST FACILITY BPX.JOBNAME AUTHUSER -``` - -Additionally, you need to activate facility class, permit `BPX.JOBNAME`, and refresh facility class: -``` -SETROPTS CLASSACT(FACILITY) RACLIST(FACILITY) -PERMIT BPX.JOBNAME CLASS(FACILITY) ID(ZWESVUSR) ACCESS(READ) -SETROPTS RACLIST(FACILITY) REFRESH -``` - -For more information, see [Setting up the UNIX-related FACILITY and SURROGAT class profiles](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.bpxb200/fclass.htm) in the "z/OS UNIX System Services" documentation. - ### Configure multi-user address space (for TSS only) The Zowe server started task `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. diff --git a/docs/user-guide/systemrequirements-zos.md b/docs/user-guide/systemrequirements-zos.md index acfd4521fa..ba96d844d9 100644 --- a/docs/user-guide/systemrequirements-zos.md +++ b/docs/user-guide/systemrequirements-zos.md @@ -107,3 +107,6 @@ Zowe consumption reference data were measured with the default Zowe configuratio - For production use of Zowe, we recommend configuring z/OSMF to leverage Zowe functionalities that require z/OSMF. For more information, see [Configuring z/OSMF](systemrequirements-zosmf.md). - For non-production use of Zowe (such as development, proof-of-concept, demo), you can customize the configuration of z/OSMF to create **_z/OS MF Lite_** to simplify your setup of z/OSMF. z/OS MF Lite only supports selected REST services (JES, DataSet/File, TSO and Workflow), resulting in considerable improvements in startup time as well as a reduction in steps to set 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). ::: + +:::note +For specific z/OS security configuration options according to your \ No newline at end of file From 8f637e9f2c6bbaf5dbfbf42a00ef5cff70a00bd9 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 4 Nov 2024 12:28:16 +0100 Subject: [PATCH 08/67] readd Configure address space job naming Signed-off-by: Andrew Jandacek --- docs/user-guide/configure-zos-system.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/user-guide/configure-zos-system.md b/docs/user-guide/configure-zos-system.md index 5d1400ca99..d4a3a7ce34 100644 --- a/docs/user-guide/configure-zos-system.md +++ b/docs/user-guide/configure-zos-system.md @@ -54,6 +54,28 @@ Be sure your z/OS system meets the following prerequisites: | To use Single Sign-On (SSO) | | [Single Sign-On (SSO)](#single-sign-on-sso) | | To use OIDC Authentication with API Mediation Layer | API ML | [API Mediation Layer OIDC Authentication](#api-mediation-layer-oidc-authentication) | +### Configure address space job naming + +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. + +:::note +This procedure may require security administrator authorization. Consult with your security administrator. +::: + +To display who is authorized to the profile, issue the following command: +``` +RLIST FACILITY BPX.JOBNAME AUTHUSER +``` + +Additionally, you need to activate facility class, permit `BPX.JOBNAME`, and refresh facility class: +``` +SETROPTS CLASSACT(FACILITY) RACLIST(FACILITY) +PERMIT BPX.JOBNAME CLASS(FACILITY) ID(ZWESVUSR) ACCESS(READ) +SETROPTS RACLIST(FACILITY) REFRESH +``` + +For more information, see [Setting up the UNIX-related FACILITY and SURROGAT class profiles](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.bpxb200/fclass.htm) in the "z/OS UNIX System Services" documentation. + ### Configure an ICSF cryptographic services environment The zssServer uses cookies that require random number generation for security. To learn more about the zssServer, see the [Zowe architecture](../getting-started/zowe-architecture.md#zss). Integrated Cryptographic Service Facility (ICSF) is a secure way to generate random numbers. From d7cb4e91c96abe643ab6278f12ceeeb0f078395f Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 4 Nov 2024 14:04:48 +0100 Subject: [PATCH 09/67] formatting Signed-off-by: Andrew Jandacek --- docs/user-guide/configure-zos-system.md | 53 +++++++++++++++++++++---- 1 file changed, 45 insertions(+), 8 deletions(-) diff --git a/docs/user-guide/configure-zos-system.md b/docs/user-guide/configure-zos-system.md index d4a3a7ce34..cdcfe009ee 100644 --- a/docs/user-guide/configure-zos-system.md +++ b/docs/user-guide/configure-zos-system.md @@ -97,7 +97,9 @@ Define or check the following configurations depending on whether ICSF is alread
- For RACF, click here for command details. + +For RACF, click here for command details. + If you use RACF, issue the following commands: ``` @@ -121,7 +123,8 @@ SETROPTS RACLIST(CSFSERV) REFRESH
- For ACF2, click here for command details. + +For ACF2, click here for command details. If you use ACF2, issue the following commands (note that `profile-prefix` and `profile-suffix` are user-defined): @@ -154,7 +157,8 @@ F ACF2,REBUILD(CSF)
- For Top Secret, click here for command details. + +For Top Secret, click here for command details. If you use Top Secret, issue the following command (note that `profile-prefix` and `profile-suffix` are user defined): @@ -192,7 +196,8 @@ You can issue the following commands first to check whether you already have the
- For RACF, click here for command details. + +For RACF, click here for command details. If you use RACF, issue the following commands: @@ -206,6 +211,7 @@ RLIST FACILITY BPX.DAEMON AUTHUSER
+ For Top Secret, click here for command details. @@ -221,6 +227,7 @@ TSS WHOHAS IBMFAC(BPX.DAEMON)
+ For ACF2, click here for command details. @@ -238,6 +245,7 @@ LIST BPX If the user `ZWESVUSR` who runs the Zowe server started task does not have UPDATE access to both profiles follow the instructions according to your ESM.
+ For RACF, click here for procedure details. @@ -283,7 +291,9 @@ RLIST FACILITY BPX.DAEMON AUTHUSER
- For Top Secret, click here for procedure details. + + +For Top Secret, click here for procedure details. If you use Top Secret, complete the following steps: @@ -310,6 +320,7 @@ TSS WHOHAS IBMFAC(BPX.DAEMON)
+ For ACF2, click here for procedure details. @@ -337,12 +348,15 @@ SET RESOURCE(FAC) ``` LIST BPX ``` +
You must also grant READ access to the OMVSAPPL profile in the APPL class to the Zowe STC user as well as **all other Zowe users** using various Zowe features. Skip the following steps when the OMVSAPPL profile is not defined in your environment.
-For RACF, click here for procedure details. + + +For RACF, click here for procedure details. If you use RACF, complete the following steps: @@ -361,7 +375,9 @@ SETROPTS RACLIST(APPL) REFRESH
-For Top Secret, click here for procedure details. + + +For Top Secret, click here for procedure details. If you use Top Secret, complete the following steps: @@ -375,10 +391,13 @@ TSS WHOHAS APPL(OMVSAPPL) ``` TSS PERMIT() APPL(OMVSAPPL) ``` +
-For ACF2, click here for procedure details. + + +For ACF2, click here for procedure details. If you use ACF2, complete the following steps: @@ -395,6 +414,7 @@ SET RESOURCE(APL) RECKEY OMVSAPPL ADD(SERVICE(READ) ROLE() ALLOW) F ACF2,REBUILD(APL) ``` +
### Configure multi-user address space (for TSS only) @@ -485,6 +505,7 @@ If you have run `ZWESECUR`, you do not need to perform the steps described in th 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.
+ For RACF, click here for command details. @@ -498,6 +519,7 @@ SETROPTS REFRESH RACLIST(STARTED)
+ For ACF2, click here for command details. @@ -513,6 +535,7 @@ F ACF2,REFRESH(STC)
+ For Top Secret, click here for command details. @@ -584,6 +607,7 @@ If you use RACF, issue the following commands:
+ For ACF2, click here for command details. @@ -603,6 +627,7 @@ F ACF2,REBUILD(FAC)
+ For Top Secret, click here for command details. @@ -629,6 +654,7 @@ This security configuration is necessary for API ML to be able to map client cer To set up this security configuration, submit the `ZWESECUR` JCL member. For users upgrading from version 1.18 and lower use the following configuration steps.
+ For RACF, click here for procedure details. @@ -654,6 +680,7 @@ If you use RACF, verify and update permission in the `FACILITY` class.
+ For ACF2, click here for procedure details. @@ -681,6 +708,7 @@ If you use ACF2, verify and update permission in the `FACILITY` class.
+ For Top Secret, click here for procedure details. @@ -706,6 +734,7 @@ This security configuration is necessary for API ML to be able to map the associ To set up this security configuration, submit the `ZWESECUR` JCL member. For users upgrading from version 1.28 and lower, use the following configuration steps.
+ For RACF, click here for procedure details. @@ -739,6 +768,7 @@ If you use RACF, verify and update permission in the `FACILITY` class.
+ For ACF2, click here for procedure details. @@ -766,6 +796,7 @@ If you use ACF2, verify and update permission in the `FACILITY` class.
+ For Top Secret, click here for procedure details. @@ -811,6 +842,7 @@ To set up this security configuration, submit the `ZWESECUR` JCL member. For use To check whether you already have the auditing profile defined, issue the following command and review the output to confirm that the profile exists and that the user `ZWESVUSR` who runs the `ZWESLSTC` started task has READ access to this profile.
+ For RACF, click here for command details. @@ -823,6 +855,7 @@ RLIST FACILITY IRR.RAUDITX AUTHUSER
+ For Top Secret, click here for command details. @@ -835,6 +868,7 @@ TSS WHOHAS IBMFAC(IRR.RAUDITX)
+ For ACF2, click here for command details. @@ -851,6 +885,7 @@ LIST LIKE(IRR-) If the user `ZWESVUSR` who runs the `ZWESLSTC` started task does not have READ access to this profile, follow the procedure that corresponds to your ESM.
+ For RACF, click here for procedure details. @@ -870,6 +905,7 @@ If you use RACF, update permission in the `FACILITY` class.
+ For Top Secret, click here for procedure details. @@ -882,6 +918,7 @@ TSS PER(ZWESVUSR) IBMFAC(IRR.RAUDITX) ACCESS(READ)
+ For ACF2, click here for procedure details. From e50bbd083a661137f5cf4d5517c43e8bf56de25d Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 4 Nov 2024 15:17:24 +0100 Subject: [PATCH 10/67] formatting Signed-off-by: Andrew Jandacek --- docs/user-guide/configure-zos-system.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/configure-zos-system.md b/docs/user-guide/configure-zos-system.md index cdcfe009ee..5e969836b1 100644 --- a/docs/user-guide/configure-zos-system.md +++ b/docs/user-guide/configure-zos-system.md @@ -121,8 +121,8 @@ SETROPTS RACLIST(CSFSERV) REFRESH
-
+
For ACF2, click here for command details. From 118ec2f5c1d3103b8b745be8f674a78053eb9460 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 4 Nov 2024 15:43:18 +0100 Subject: [PATCH 11/67] formatting Signed-off-by: Andrew Jandacek --- docs/user-guide/configure-zos-system.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/user-guide/configure-zos-system.md b/docs/user-guide/configure-zos-system.md index 5e969836b1..0028413aee 100644 --- a/docs/user-guide/configure-zos-system.md +++ b/docs/user-guide/configure-zos-system.md @@ -121,11 +121,8 @@ SETROPTS RACLIST(CSFSERV) REFRESH
-
- -For ACF2, click here for command details. - +For ACF2, click here for command details. If you use ACF2, issue the following commands (note that `profile-prefix` and `profile-suffix` are user-defined): From 1faea93204ee6d3aeda3ac3bf3868bac65c290f7 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 4 Nov 2024 15:55:17 +0100 Subject: [PATCH 12/67] remove summary for ACF2 Signed-off-by: Andrew Jandacek --- docs/user-guide/configure-zos-system.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/configure-zos-system.md b/docs/user-guide/configure-zos-system.md index 0028413aee..74ab1a7bcc 100644 --- a/docs/user-guide/configure-zos-system.md +++ b/docs/user-guide/configure-zos-system.md @@ -121,8 +121,8 @@ SETROPTS RACLIST(CSFSERV) REFRESH
-
-For ACF2, click here for command details. +For ACF2, click here for command details. + If you use ACF2, issue the following commands (note that `profile-prefix` and `profile-suffix` are user-defined): @@ -150,8 +150,6 @@ RECKEY profile-prefix ADD(profile-suffix uid(UID string for IZUSVR) SERVICE(READ F ACF2,REBUILD(CSF) ``` -
-
From ef69d938208f8681f18dd54d97f26f0221cc7c5d Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 4 Nov 2024 16:09:58 +0100 Subject: [PATCH 13/67] re add ACF2 collapsable content Signed-off-by: Andrew Jandacek --- docs/user-guide/configure-zos-system.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/user-guide/configure-zos-system.md b/docs/user-guide/configure-zos-system.md index 74ab1a7bcc..1c40714c4c 100644 --- a/docs/user-guide/configure-zos-system.md +++ b/docs/user-guide/configure-zos-system.md @@ -121,7 +121,11 @@ SETROPTS RACLIST(CSFSERV) REFRESH
+
+ + For ACF2, click here for command details. + If you use ACF2, issue the following commands (note that `profile-prefix` and `profile-suffix` are user-defined): @@ -149,6 +153,7 @@ RECKEY profile-prefix ADD(profile-suffix uid(UID string for IZUSVR) SERVICE(READ ``` F ACF2,REBUILD(CSF) ``` +
From 8affbc37d7d884b41c8fd4952aa8db80fb8fe51b Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 4 Nov 2024 16:33:17 +0100 Subject: [PATCH 14/67] fix note at the bottom of systemrequirements-zos Signed-off-by: Andrew Jandacek --- docs/user-guide/systemrequirements-zos.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/systemrequirements-zos.md b/docs/user-guide/systemrequirements-zos.md index ba96d844d9..58930418a5 100644 --- a/docs/user-guide/systemrequirements-zos.md +++ b/docs/user-guide/systemrequirements-zos.md @@ -109,4 +109,5 @@ Zowe consumption reference data were measured with the default Zowe configuratio ::: :::note -For specific z/OS security configuration options according to your \ No newline at end of file +For specific z/OS security configuration options that apply to the specific Zowe server-side components in your configuration, see [Security customization of your z/OS system](./configure-zos-system.md). +::: From afcda3e1c0f2599a7df172a8040ad3a85cb91512 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Tue, 5 Nov 2024 13:49:20 +0100 Subject: [PATCH 15/67] address Sean's comments Signed-off-by: Andrew Jandacek --- docs/user-guide/configure-zos-system.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/user-guide/configure-zos-system.md b/docs/user-guide/configure-zos-system.md index 1c40714c4c..7f765ed0bc 100644 --- a/docs/user-guide/configure-zos-system.md +++ b/docs/user-guide/configure-zos-system.md @@ -41,17 +41,17 @@ Be sure your z/OS system meets the following prerequisites: | --- | --- | --- | | Set the names for the different z/OS UNIX address spaces for the Zowe runtime components.
**Important:** This configuration step is required. | All components | [Configure address space job naming](#configure-address-space-job-naming) | | To use Zowe desktop. This step generates random numbers for zssServer that the Zowe desktop uses. | Application Framework | [Configure an ICSF cryptographic services environment](#configure-an-icsf-cryptographic-services-environment) | -| To allow users to log on to the Zowe desktop through impersonation. | | [Configure security environment switching](#configure-security-environment-switching) | -| Required for TSS only. A TSS FACILITY needs to be defined and assigned to the `ZWESLSTC` started task. | | [Configure multi-user address space for TSS only](#configure-multi-user-address-space-for-tss-only) | -| Required if you have not run `ZWESECUR` and are manually creating the user ID and groups in your z/OS environment. | | [Configure user IDs and groups for the Zowe started tasks](#configure-user-ids-and-groups-for-the-zowe-started-tasks) | -| Required if you have not run `ZWESECUR` and are configuring your z/OS environment manually. This step describes how to configure the started task ZWESLSTC to run under the correct user ID and group. | | [Configure ZWESLSTC to run Zowe high availability instances under ZWESVUSR user ID](#configure-zweslstc-to-run-zowe-high-availability-instances-under-zwesvusr-user-id) | -| Required if you have not run `ZWESECUR` and are configuring your z/OS environment manually. This step describes how to configure the cross memory server for SAF to guard against access by non-privileged clients. | Application Framework | [Configure the cross memory server for SAF](#configure-the-cross-memory-server-for-saf) | +| To allow users to log on to the Zowe desktop through impersonation. | Application Framework | [Configure security environment switching](#configure-security-environment-switching) | +| Required for TSS only. A TSS FACILITY needs to be defined and assigned to the `ZWESLSTC` started task. | ? | [Configure multi-user address space for TSS only](#configure-multi-user-address-space-for-tss-only) | +| Required to manually create the user ID and groups in your z/OS environment. Tasks are performed as part of [Zowe runtime configuration](./configure-zowe-runtime.md) | ? | [Configure user IDs and groups for the Zowe started tasks](#configure-user-ids-and-groups-for-the-zowe-started-tasks) | +| Required to configure the started task ZWESLSTC to run under the correct user ID and group. Tasks are performed as part of [Zowe runtime configuration](./configure-zowe-runtime.md).| ? | [Configure ZWESLSTC to run Zowe high availability instances under ZWESVUSR user ID](#configure-zweslstc-to-run-zowe-high-availability-instances-under-zwesvusr-user-id). | +| Required to configure the cross memory server for SAF to guard against access by non-privileged clients. Tasks are performed as part of [Zowe runtime configuration](./configure-zowe-runtime.md).| Application Framework | [Configure the cross memory server for SAF](#configure-the-cross-memory-server-for-saf) | | Required for API Mediation Layer to map a client certificate to a z/OS identity. | API ML | [Configure main Zowe server to use client certificate identity mapping](#configure-main-zowe-server-to-use-client-certificate-identity-mapping) | | Required for API ML to map the association between a z/OS user ID and a distributed user identity. | API ML | [Configure main Zowe server to use distributed identity mapping](#configure-main-zowe-server-to-use-distributed-identity-mapping) | -| To configure SAF Identity tokens on z/OS so that they can be used by Zowe components like zss or API Mediation Layer. | | [Configure signed SAF Identity tokens IDT](#configure-signed-saf-identity-tokens-idt) | +| To configure SAF Identity tokens on z/OS so that they can be used by Zowe components like zss or API Mediation Layer. | Application Framework
API ML | [Configure signed SAF Identity tokens IDT](#configure-signed-saf-identity-tokens-idt) | | Required for API Mediation Layer to issue SMF records. | API ML | [Configure the main Zowe server to issue SMF records](api-mediation/api-mediation-smf.md#configure-the-main-zowe-server-to-issue-smf-records) | -| To use multi-factor authentication (MFA) | | [Multi-Factor Authentication (MFA)](#multi-factor-authentication-mfa) | -| To use Single Sign-On (SSO) | | [Single Sign-On (SSO)](#single-sign-on-sso) | +| To use multi-factor authentication (MFA) | ? | [Multi-Factor Authentication (MFA)](#multi-factor-authentication-mfa) | +| To use Single Sign-On (SSO) | ? | [Single Sign-On (SSO)](#single-sign-on-sso) | | To use OIDC Authentication with API Mediation Layer | API ML | [API Mediation Layer OIDC Authentication](#api-mediation-layer-oidc-authentication) | ### Configure address space job naming From f0077ec254d985a99b78d697bdb820b008d02109 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Tue, 5 Nov 2024 15:20:52 +0100 Subject: [PATCH 16/67] add link to zwe init security Signed-off-by: Andrew Jandacek --- docs/user-guide/initialize-zos-system.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/user-guide/initialize-zos-system.md b/docs/user-guide/initialize-zos-system.md index 349f87b80c..2af842fdd1 100644 --- a/docs/user-guide/initialize-zos-system.md +++ b/docs/user-guide/initialize-zos-system.md @@ -24,6 +24,8 @@ Configures the VSAM files needed if the Caching service is set to VSAM mode. Thi :::info Recommendation: We recommend you to run these sub commands one by one to clearly see the output of each step. To successfully run `zwe init security`, `zwe init apfauth`, and `zwe init certificate`, it is likely that your organization requires elevated permissions. We recommend you consult with your security administrator to run these commands. For more information about tasks for the security administrator, see the section [Configuring security](./configuring-security.md) in this configuration documentation. + +For information about the `zwe init security` command, see [configuring with `zwe init security` command](./initialize-security-configuration.md#configuring-with-zwe-init-security-command). ::: :::tip From 1839c4b49dc862b2e331220475009bc3cfe26ef7 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Tue, 5 Nov 2024 16:10:40 +0100 Subject: [PATCH 17/67] fix typo and add roles Signed-off-by: Andrew Jandacek --- docs/user-guide/configure-zowe-runtime.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/configure-zowe-runtime.md b/docs/user-guide/configure-zowe-runtime.md index 53efa6b085..f826ee8cb3 100644 --- a/docs/user-guide/configure-zowe-runtime.md +++ b/docs/user-guide/configure-zowe-runtime.md @@ -10,14 +10,14 @@ Use one of the following options to initialize Zowe z/OS runtime: * Initialize Zowe maunually using zwe init command group * Configure Zowe with z/OSMF workflows -## Initialize Zowe maunually using zwe init command group +## Initialize Zowe manually using zwe init command group After your installation of Zowe runtime, you can run the `zwe init` command to perform the following configurations: * Initialize Zowe with copies of data sets provided with Zowe -* Create user IDs and security manager settings -* Provide APF authorize load libraries -* Configure Zowe to use TLS certificates +* Create user IDs and security manager settings (Security Admin) +* Provide APF authorize load libraries (Security Admin) +* Configure Zowe to use TLS certificates (Security Admin) * Configure VSAM files to run the Zowe caching service used for high availability (HA) * Configure the system to launch the Zowe started task From 9b9f049cc09c87e00a186bb5ee4a2a83b7c33699 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 7 Nov 2024 10:54:05 +0100 Subject: [PATCH 18/67] shuffle content from initializing Zowe security configuration into Configuring security / limit content duplication Signed-off-by: Andrew Jandacek --- docs/user-guide/configuring-security.md | 73 ++++++++++++++++++- .../initialize-security-configuration.md | 3 + docs/user-guide/initialize-zos-system.md | 1 + .../zwe-init-subcommand-overview.md | 40 ++++++++-- 4 files changed, 108 insertions(+), 9 deletions(-) diff --git a/docs/user-guide/configuring-security.md b/docs/user-guide/configuring-security.md index 221504a5c2..6e441a88af 100644 --- a/docs/user-guide/configuring-security.md +++ b/docs/user-guide/configuring-security.md @@ -11,12 +11,79 @@ During installation, the system programmer customizes values in the zowe.yaml fi ## Initialize Zowe security configurations +This security configuration step is required for first time setup of Zowe. If Zowe has already been launched on a z/OS system from a previous release of Zowe v2, and the `zwe init security` subcommand successfully ran when initializing the z/OS subsystem, you can skip this step unless told otherwise in the release documentation. + Choose from the following methods to initialize Zowe security configurations: -* Configuring with `zwe init security` -* Configuring with `ZWESECUR` JCL +* Configuring with `zwe init security` command +* Configuring with `ZWESECUR` JCL + +## Configuring with `zwe init security` command + +The `zwe init security` command reads data from `zowe.yaml` and constructs a JCL member using `ZWESECUR` as a template which is then submitted. This is a convenience step to assist with driving Zowe configuration through a pipeline or when you prefer to use USS commands rather than directly edit and customize JCL members. + +:::note +If you do not have permissions to update your security configurations, use the `security-dry-run` described in the following tip. We recommend you inform your security administrator to review the `ZWESECUR` job content. +::: + +:::tip + +To avoid having to run the `init security` command, you can specify the parameter `--security-dry-run`. This parameter enables you to construct a JCL member containing the security commmands without running the member. This is useful for previewing commands and can also be used to copy and paste commands into a TSO command prompt for step by step manual execution. + +**Example:** + +``` +#>zwe init security -c ./zowe.yaml --security-dry-run +------------------------------------------------------------------------------- +>> Run Zowe security configurations + +Modify ZWESECUR +- IBMUSER.ZWEV2.CUST.JCLLIB(ZW134428) is prepared + +Dry-run mode, security setup is NOT performed on the system. +Please submit IBMUSER.ZWEV2.CUST.JCLLIB(ZW134428) manually. +>> Zowe security configurations are applied successfully. + +#> +``` +::: + + + +## Configuring with `ZWESECUR` JCL + +An alternative to using `zwe init security` is to prepare a JCL member to configure the z/OS system, and edit `ZWESECUR` to make changes. + +The JCL allows you to vary which security manager you use by setting the _PRODUCT_ variable to be one of the following ESMs: +* `RACF` +* `ACF2` +* `TSS`. + +**Example:** +``` +// SET PRODUCT=RACF * RACF, ACF2, or TSS +``` + +If `ZWESECUR` encounters an error or a step that has already been performed, it continues to the end, so it can be run repeatedly in a scenario such as a pipeline automating the configuration of a z/OS environment for Zowe installation. + +:::info Important +It is expected that your security administrator will be required to review, edit where necessary, and either execute `ZWESECUR` as a single job, or execute individual TSO commands to complete the security configuration of a z/OS system in preparation for installing and running Zowe. +::: + +The following video shows how to locate the `ZWESECUR` JCL member and execute it. + + + + + +### Undo security configurations + +To undo all of the z/OS security configuration steps performed by the JCL member `ZWESECUR`, use the reverse member `ZWENOSEC`. This member contains steps that reverse steps performed by `ZWESECUR`. This is useful in the following situations: + +- You are configuring z/OS systems as part of a build pipeline that you want to undo, and redo configuration and installation of Zowe using automation. +- You configured a z/OS system for Zowe that you no longer want to use, and you prefer to delete the Zowe user IDs and undo the security configuration settings rather than leave them enabled. -For more information about both of these methods, see [Initialize Zowe security configurations](./initialize-security-configuration.md). +If you run `ZWENOSEC` on a z/OS system, it is necessary to rerun `ZWESECUR` to reinitialize the z/OS security configuration. Zowe cannot be run until `ZWESECUR` is rerun. ## Perform APF authorization of load libraries diff --git a/docs/user-guide/initialize-security-configuration.md b/docs/user-guide/initialize-security-configuration.md index 965b2590a4..f55102ebdd 100644 --- a/docs/user-guide/initialize-security-configuration.md +++ b/docs/user-guide/initialize-security-configuration.md @@ -1,5 +1,8 @@ # Initializing Zowe security configurations + + + This security configuration step is required for first time setup of Zowe. If Zowe has already been launched on a z/OS system from a previous release of Zowe v2, and the `zwe init security` subcommand successfully ran when initializing the z/OS subsystem, you can skip this step unless told otherwise in the release documentation. :::info Required roles: system programmer, security administrator diff --git a/docs/user-guide/initialize-zos-system.md b/docs/user-guide/initialize-zos-system.md index 2af842fdd1..c96f599fe9 100644 --- a/docs/user-guide/initialize-zos-system.md +++ b/docs/user-guide/initialize-zos-system.md @@ -25,6 +25,7 @@ Configures the VSAM files needed if the Caching service is set to VSAM mode. Thi :::info Recommendation: We recommend you to run these sub commands one by one to clearly see the output of each step. To successfully run `zwe init security`, `zwe init apfauth`, and `zwe init certificate`, it is likely that your organization requires elevated permissions. We recommend you consult with your security administrator to run these commands. For more information about tasks for the security administrator, see the section [Configuring security](./configuring-security.md) in this configuration documentation. + For information about the `zwe init security` command, see [configuring with `zwe init security` command](./initialize-security-configuration.md#configuring-with-zwe-init-security-command). ::: diff --git a/docs/user-guide/zwe-init-subcommand-overview.md b/docs/user-guide/zwe-init-subcommand-overview.md index fa21b906c8..b5ee1db520 100644 --- a/docs/user-guide/zwe-init-subcommand-overview.md +++ b/docs/user-guide/zwe-init-subcommand-overview.md @@ -6,11 +6,15 @@ Review this article to learn about the individual subcommands executed in `zwe i Some of the following `zwe init` subcommands require elevated permissions. See the required roles associated with each of these commands. ::: -* [Initializing Zowe custom data sets (`zwe init mvs`)](#initializing-zowe-custom-data-sets-zwe-init-mvs) -* [Initializing Zowe security configurations (`zwe init security`)](#initializing-zowe-security-configurations-zwe-init-security) -* [Performing APF authorization of load libraries (`zwe init apfauth`)](#performing-apf-authorization-of-load-libraries-zwe-init-apfauth) -* [Configuring Zowe to use TLS certificates (`zwe init certificate`)](#configuring-zowe-to-use-tls-certificates-zwe-init-certificate) -* [Installing Zowe main started tasks (`zwe init stc`)](#installing-zowe-main-started-tasks-zwe-init-stc) +- [zwe init subcommand overview](#zwe-init-subcommand-overview) + - [Initializing Zowe custom data sets (`zwe init mvs`)](#initializing-zowe-custom-data-sets-zwe-init-mvs) + - [Procedure to initialize Zowe custom data sets](#procedure-to-initialize-zowe-custom-data-sets) + - [Initializing Zowe security configurations (`zwe init security`)](#initializing-zowe-security-configurations-zwe-init-security) + - [Performing APF authorization of load libraries (`zwe init apfauth`)](#performing-apf-authorization-of-load-libraries-zwe-init-apfauth) + - [Configuring Zowe to use TLS certificates (`zwe init certificate`)](#configuring-zowe-to-use-tls-certificates-zwe-init-certificate) + - [Installing Zowe main started tasks (`zwe init stc`)](#installing-zowe-main-started-tasks-zwe-init-stc) + - [(Deprecated) Creating VSAM caching service datasets (`zwe init vsam`)](#deprecated-creating-vsam-caching-service-datasets-zwe-init-vsam) + - [Next steps](#next-steps) ## Initializing Zowe custom data sets (`zwe init mvs`) @@ -108,7 +112,31 @@ If Zowe has already been launched on a z/OS system from a previous release of Zo The JCL member `.SZWESAMP(ZWESECUR)` is provided to assist with the security configuration. Before submitting the `ZWESECUR` JCL member, customize this member to match site security rules. For script driven scenarios, you can run the command `zwe init security` which uses `ZWESECUR` as a template to create a customized member in `.CUST.JCLLIB`. This member contains the commands required to perform the security configuration. -For more information about `zwe init security`, see [Initializing Zowe security configurations](./initialize-security-configuration). +For more information about `zwe init security`, see [Configuring with `zwe init security` command](./configuring-security.md#configuring-with-zwe-init-security-command). + +:::tip + +To avoid having to run the `init security` command, you can specify the parameter `--security-dry-run`. This parameter enables you to construct a JCL member containing the security commmands without running the member. This is useful for previewing commands and can also be used to copy and paste commands into a TSO command prompt for step by step manual execution. + +**Example:** + +``` +#>zwe init security -c ./zowe.yaml --security-dry-run +------------------------------------------------------------------------------- +>> Run Zowe security configurations + +Modify ZWESECUR +- IBMUSER.ZWEV2.CUST.JCLLIB(ZW134428) is prepared + +Dry-run mode, security setup is NOT performed on the system. +Please submit IBMUSER.ZWEV2.CUST.JCLLIB(ZW134428) manually. +>> Zowe security configurations are applied successfully. + +#> +``` +For production environments, inform your security administrator to re-submit the `init security` command with proper authorization. + +::: ## Performing APF authorization of load libraries (`zwe init apfauth`) From fa3bf2dd754ba362d72c38fd2236fb943a54fa77 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 7 Nov 2024 11:42:27 +0100 Subject: [PATCH 19/67] create collapsible content for zwe seucity and JCL options Signed-off-by: Andrew Jandacek --- docs/user-guide/configuring-security.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/configuring-security.md b/docs/user-guide/configuring-security.md index 6e441a88af..e23b8d4d9f 100644 --- a/docs/user-guide/configuring-security.md +++ b/docs/user-guide/configuring-security.md @@ -7,18 +7,18 @@ During the initial installation of Zowe server-side components, it is necessary ## Validate and re-run `zwe init` commands -During installation, the system programmer customizes values in the zowe.yaml file. However, due to insufficient permissions of the system programmer, the `zwe init security` command may fail. Consult with your security administrator to review your `ZWESECUR` job content so that your security adminstrator can re-submit this JCL. +During installation, the system programmer customizes values in the zowe.yaml file. However, due to insufficient permissions of the system programmer, the `zwe init security` command may fail without sufficient user authorization. ## Initialize Zowe security configurations -This security configuration step is required for first time setup of Zowe. If Zowe has already been launched on a z/OS system from a previous release of Zowe v2, and the `zwe init security` subcommand successfully ran when initializing the z/OS subsystem, you can skip this step unless told otherwise in the release documentation. +This security configuration step is required for first time setup of Zowe and may require security autorization. If Zowe has already been launched on a z/OS system from a previous release of Zowe v2, and the `zwe init security` subcommand successfully ran when initializing the z/OS subsystem, you can skip this step unless told otherwise in the release documentation. Choose from the following methods to initialize Zowe security configurations: -* Configuring with `zwe init security` command -* Configuring with `ZWESECUR` JCL +
+Click here to configure with the `zwe init security` command. -## Configuring with `zwe init security` command +**Configure with `zwe init security` command** The `zwe init security` command reads data from `zowe.yaml` and constructs a JCL member using `ZWESECUR` as a template which is then submitted. This is a convenience step to assist with driving Zowe configuration through a pipeline or when you prefer to use USS commands rather than directly edit and customize JCL members. @@ -48,9 +48,15 @@ Please submit IBMUSER.ZWEV2.CUST.JCLLIB(ZW134428) manually. ``` ::: +
+ -## Configuring with `ZWESECUR` JCL +
+Click here to configure with `ZWESECUR` JCL. + + +**Configure with `ZWESECUR` JCL** An alternative to using `zwe init security` is to prepare a JCL member to configure the z/OS system, and edit `ZWESECUR` to make changes. @@ -74,6 +80,8 @@ The following video shows how to locate the `ZWESECUR` JCL member and execute it +
+ ### Undo security configurations From 556b92e97815c3e9048ef6665cb7898d2ea01207 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 7 Nov 2024 15:08:21 +0100 Subject: [PATCH 20/67] note refactoring Signed-off-by: Andrew Jandacek --- docs/user-guide/configuring-security.md | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/docs/user-guide/configuring-security.md b/docs/user-guide/configuring-security.md index e23b8d4d9f..d0113aefe7 100644 --- a/docs/user-guide/configuring-security.md +++ b/docs/user-guide/configuring-security.md @@ -5,13 +5,18 @@ During the initial installation of Zowe server-side components, it is necessary :::info Required roles: system programmer, security administrator ::: +:::note +For initial tasks to be performed by the security administrator before Zowe server-side installation, see [Addressing security requirements](./address-security-requirements.md). + +::: + ## Validate and re-run `zwe init` commands During installation, the system programmer customizes values in the zowe.yaml file. However, due to insufficient permissions of the system programmer, the `zwe init security` command may fail without sufficient user authorization. ## Initialize Zowe security configurations -This security configuration step is required for first time setup of Zowe and may require security autorization. If Zowe has already been launched on a z/OS system from a previous release of Zowe v2, and the `zwe init security` subcommand successfully ran when initializing the z/OS subsystem, you can skip this step unless told otherwise in the release documentation. +This security configuration step is required for first time setup of Zowe and may require security authorization. If Zowe has already been launched on a z/OS system from a previous release of Zowe v2, and the `zwe init security` subcommand successfully ran when initializing the z/OS subsystem, you can skip this step unless told otherwise in the release documentation. Choose from the following methods to initialize Zowe security configurations: @@ -97,9 +102,9 @@ If you run `ZWENOSEC` on a z/OS system, it is necessary to rerun `ZWESECUR` to r Zowe contains load modules that require access to make privileged z/OS security manager calls. These load modules are held in two load libraries which must be APF authorized. For more information about how to issue the `zwe init apfauth` command to perform APF authority commands, see [Performing APF authorization of load libraries](./apf-authorize-load-library.md). -## Configure the z/OS system for Zowe +## Customize security of your z/OS system -Review and perform z/OS configuration steps based on your settings. For a detailed table of configuration procedures and associated purposes for performing these procedures, see [Configuring the z/OS system for Zowe](./configure-zos-system.md). +Review and perform z/OS configuration steps based on your settings. For a detailed table of configuration procedures and associated purposes for performing these procedures, see [Security customization of your z/OS system](./configure-zos-system.md). ## Assign security permissions to users @@ -123,15 +128,4 @@ Depending on the specific Zowe server-side components that your organization is ## Next steps -After these security configuration steps are completed, and [Zowe z/OS runtime is initialized](./configure-zowe-runtime.md), the next step is [Configuring certificates](./configure-certificates.md). -Note that configuring certificates requires security administrator authorization. - -:::note -For more information about security administrator tasks, see: -* [Addressing security requirements](./address-security-requirements.md) -* [Configuring security](./configuring-security.md) -* [Configuring certificates](./configure-certificates.md) -::: - - - \ No newline at end of file +After Zowe z/OS runtime is initialized, and you complete other procedures in the Configuring security section, the next step is [Configuring certificates](./configure-certificates.md). From b0ff7b36fbef4dcbd3d4c800c53bff7a67aa1d6c Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Fri, 8 Nov 2024 11:11:45 +0100 Subject: [PATCH 21/67] fix link Signed-off-by: Andrew Jandacek --- docs/user-guide/zwe-init-subcommand-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/zwe-init-subcommand-overview.md b/docs/user-guide/zwe-init-subcommand-overview.md index b5ee1db520..44a6164100 100644 --- a/docs/user-guide/zwe-init-subcommand-overview.md +++ b/docs/user-guide/zwe-init-subcommand-overview.md @@ -112,7 +112,7 @@ If Zowe has already been launched on a z/OS system from a previous release of Zo The JCL member `.SZWESAMP(ZWESECUR)` is provided to assist with the security configuration. Before submitting the `ZWESECUR` JCL member, customize this member to match site security rules. For script driven scenarios, you can run the command `zwe init security` which uses `ZWESECUR` as a template to create a customized member in `.CUST.JCLLIB`. This member contains the commands required to perform the security configuration. -For more information about `zwe init security`, see [Configuring with `zwe init security` command](./configuring-security.md#configuring-with-zwe-init-security-command). +For more information about `zwe init security`, see _Configure with `zwe init security` command_ in [Configuring security](./configuring-security.md). :::tip From 5e5037ec5ee2ce675a5a1a40512901ceb5943ac0 Mon Sep 17 00:00:00 2001 From: anaxceron Date: Thu, 14 Nov 2024 15:28:28 -0500 Subject: [PATCH 22/67] adding workflow for major release doc updates Signed-off-by: anaxceron --- release-handbook/major_release_workflow.md | 184 +++++++++++++++++++++ release-handbook/release_handbook.md | 7 +- 2 files changed, 189 insertions(+), 2 deletions(-) create mode 100644 release-handbook/major_release_workflow.md diff --git a/release-handbook/major_release_workflow.md b/release-handbook/major_release_workflow.md new file mode 100644 index 0000000000..802a58680b --- /dev/null +++ b/release-handbook/major_release_workflow.md @@ -0,0 +1,184 @@ +# How to manage doc for a major Zowe release + +Major Zowe releases follow a similar publication process to that of minor releases: content is staged, and then that content is published to the live Zowe Docs site. + +What is quite different about updating documentation for a major release is the amount and type of prep work required. To improve the chances of a smoother publication process, you will want to start preparing the doc work for a major release at least a year ahead of the major release GA date. + +Zowe major releases are typically done about every two years or so. Minor releases take place about once a calendar quarter. + +The publication process for minor releases is documented in the [Release handbook](release_handbook.md). + +For major Zowe releases, follow the process outlined here. + +## Major release publication process + +1. At least a year before the major release GA, Doc Squad works together to create a release strategy. + - Strategy to include: + - Schedule for reviewing existing content for any needed modifications + - Schedule for when modifications should be drafted, reviewed, and completed + - Complete inventory of Zowe Docs content and the people who are responsible for ensuring that content is ready for the major release. + - Assignment of responsibilities. +2. Create a new branch based off the `master` branch to be dedicated to the major release documentation. Open the new branch in Visual Studio Code. + - For example, `v3-doc-branch` was used for the Zowe V3 release. +3. Archive the documentation for the most recent (minor) release by taking the following steps in this order: + - In the Terminal, run `npm run docusaurus docs:version `. + + - *\* is the version number of the previous release. + + Example: At the time you create the new branch, Zowe 3.5 is the latest version for the current major release. That means the command must be issued as `npm run docusaurus docs:version v3.5.x` + + - When the command completes, it returns the message `[docs]: version v3.5.x created!` + + - The document versioning mechanism has: + * Copied the full `docs/` folder contents into a new `versioned_docs/version-v3.5.x/` folder. + * Created a versioned `sidebars` file based from your current sidebar configuration. The file is saved as `versioned_sidebars/version-v3.5.x-sidebars.json`. + * Appended the new version number to the `versions.json` file. + + - Archive the `/static` files: + 1. Go to the `/static` folder. + 2. Create an empty directory with the name of the previous version in `/static`. For example: `static/v3.5.x`. + 3. Copy all contents of the `/static/stable` directory and paste them in the previous version's empty directory in the previous step. For example: `/static/v3.5.x`. + + - Update a set of links in the archived documentation to ensure that they refer to the correct location: + + 1. To do this, switch to the archived directory. In our example, that's `versioned_docs/version-v3.5.x`. + + 2. Update several locations in the archived docs to refer to the correct release, the 3.5 release (in our example case). + + **Tip**: Use the **Find** function of Visual Studio Code editor to make the updates. In our example, you can right-click the `versioned_docs/version-v3.5.x` folder and then select **Find in Folder...**. + + ![Find in files in VSCode](images/vscode-find.png) + + - Search all instances of `` and replace `stable` in the link with the previous version before adding the new version. Example: ``. + + ![Update CLI web help](images/update-cli-web-help.png) + + - Search all instances of `` and replace `stable` with the previous version before adding the new version. Example: ``. + + ![Update CLI reference PDF](images/update-cli-reference.png) + + - Search all instances of `` and replace `stable` with the previous version before adding the new version. Example: ``. + + ![Update CLI web help ZIP](images/update-cli-help-zip.png) + + 3. Verify that the archived version works: + 1. Run `npm install`. + 2. Run `npm start` to build the site locally and clear any errors. + + ![Verify the archived doc](images/verify-archive.png) + + **NOTE:** When the local build displays in your web browser, expect to see the previous minor release version listed twice in the Zowe Docs version drop-down menu. You will fix this in Step 4. + +4. Bump the version of docs to the new major version (example: v4.0) by taking the following steps in this order: + - Navigate to the `/docusaurus.config.js` file. + - Change the `LATEST_VERSION` variable present in Line 1 of the `/docusaurus.config.js` file to the new major version. + - Locate the presets: `> @docusaurus/preset-classic" > docs > versions` in the `/docusaurus.config.js` file to include the previous version in the list. + - Create an entry label for the previous version. + Example: If version v3.5.x docs is getting updated to v4.0.x, then v3.5.x will be appended between `current` and `v3.4.x` in the following format: + + ``` + presets: [ + [ + "@docusaurus/preset-classic", + { + docs: { + path: "docs", + sidebarPath: require.resolve("./sidebars.js"), + editUrl: "https://github.com/zowe/docs-site/edit/master/", + showLastUpdateAuthor: false, + showLastUpdateTime: true, + routeBasePath: "/", + lastVersion: "current", + versions: { + current: { + path: "stable", + label: `${LATEST_VERSION}` + " LTS", + }, + "v3.5.x": { + label: "v3.5.x LTS", + }, + "v3.4.x": { + label: "v3.4.x LTS", + }, + ``` + + - Open the `versions.json` file. Confirm that the previous release version number was added to the top of the list. (This is typically done automatically by the command issued in Step 3.) If not, manually add the version number. For example: + + ``` + [ + "v3.5.x", + "v3.4.x", + "v3.3.x", + "v3.2.x", + "v3.1.x", + "v3.0.x" + ] + ``` + +5. Create placeholder files to prep for the release notes and TPSRs: + - In Visual Studio Code, add the release notes placeholder file for the new major release: + 1. Go to `/docs/whats-new/release-notes`. + 2. Create a file for the new version and add the outline to the document. For example: `/docs/whats-new/release-notes/v4_0_0.md` + + To insert the outline, copy and paste the template from the [Release Notes guide](release_notes_guide.md). Ensure that you update the date and release version numbers included in the template. + + 3. Open the `sidebars.js` file and add the new page to the release notes section. + ``` + { + type: "category", + label: "Release notes", + items: [ + "whats-new/release-notes/v4_0_0", + "whats-new/release-notes/v3_5_0", + "whats-new/release-notes/v3_4_0", + ], + }, + ``` + + - Add the TPSR placeholder file. + 1. Go to the `/tpsr` directory. + 2. Add a new file for the new version. For example: `/tpsr/tpsr-v4.0.x.md`. + 3. Update the TPSR file URL the `sidebar.js` file: + + ``` + { + type: "link", + label: "Third Party Software Requirements", + href: "https://github.com/zowe/docs-site/tree/master/tpsr/tpsr-v4.0.x.md", + }, + ``` + + **Note:** This is just a placeholder file. The day before GA, this file should be updated to include the information for the new release. Contact the Zowe release engineer to get the most up-to-date file. + + - Create a local build to confirm everything works in your temporary branch. + + 1. Run `npm install`. + 2. Run `npm start` to build the site locally and clear any errors. +6. Create a PR in the `docs-site` repo to merge the new branch to the `docs-staging` branch. Set the PR to draft mode. + - At this point, the branch becomes available to Zowe community members for them to make any needed doc updates. You should now decide what restrictions (if any) to put in place to protect the branch. +7. As the GA date for the major release approaches, continue to sync the new branch with `docs-staging`. Resolve any merge conflicts that show up. This might mean checking in with the Doc Squad to confirm which content is the correct content to merge. +8. The day or two before the GA date, perform Step 3 to include the last minor release of the previous major version. +9. The day or two before the GA date, contact the release engineer to get the TPSR file. Add the TPSR file contents to the TPSR placeholder file in the repo. +10. Publish the staged doc to the live site: + - Change the PR you opened in Step 6 to **Ready for review** mode to merge the new branch into the `docs-staging` branch. + - All checks **must** pass before merging. If any checks fail, troubleshoot with Doc Squad members or developers well familiar with the `docs-site` repo to resolve. + - After the new branch is merged to `docs-staging`, create a PR to merge `docs-staging` into the `master` branch. + - In your PR, do the following: + - Add the Zowe release engineer to the reviewer list. + - Add Zowe Doc Squad maintainers to the reviewer list. + - Check the build status and notify the Doc Squad of any build problems or errors. + - Once the PR checks all pass, notify the release engineer that the PR has been created and needs review. It is the engineer who will merge the PR once the new release is published. + + **Important**: Remind the engineer to merge the PR by selecting the **Create a merge commit** option. + The engineer should **NOT** commit with a **Squash and merge**, which can lead to merge conflicts for later releases. + +11. Perform post-publication tasks: + - After the vNext content is live, create and publish a PDF of the content for new major release (v4.0, in our example): + 1. Follow the instructions in [Steps to manually generate PDF](pdf_generation_guide.md#steps-to-manually-generate-pdf-recommended). + 2. Create a new temporary branch to add the PDF to the `master` branch. Create and merge a PR in GitHub. + - Check Zowe Docs to confirm the site works as expected. Confirm the following items: + - The version dropdown menu includes all available versions + - Release notes are current + - The correct TPSRs are linked + - The PDF for the current release can be downloaded and viewed + - The Search functionality returns correct results diff --git a/release-handbook/release_handbook.md b/release-handbook/release_handbook.md index c4e0aac0e9..321f69dfcf 100644 --- a/release-handbook/release_handbook.md +++ b/release-handbook/release_handbook.md @@ -67,11 +67,13 @@ Once the Code Freeze for a new release takes place, the `docs-staging` branch mu - Creating placeholder files and folders for the vNext release The following steps takes v1.25 release preparation as an example. Preparation should start the day Code Freeze takes place. + ### **Part 1: Sync the doc branches** Summary: Update the `docs-staging` branch so it includes all updates made to the `master` branch. **Procedure** + 1. Create and publish a new (temporary) branch based off the `master` branch. 2. Create a PR to merge the temporary branch into the `docs-staging` branch. @@ -137,11 +139,11 @@ Summary: Create new directories to archive content. Relocate content files for t ![Update CLI web help](images/update-cli-web-help.png) - * Search all instaces of `` and replace `stable` with the previous version before adding the new version. Example: ``. + * Search all instances of `` and replace `stable` with the previous version before adding the new version. Example: ``. ![Update CLI reference PDF](images/update-cli-reference.png) - * Search all instaces of `` and replace `stable` with the previous version before adding the new version. Example: ``. + * Search all instances of `` and replace `stable` with the previous version before adding the new version. Example: ``. ![Update CLI web help ZIP](images/update-cli-help-zip.png) @@ -219,6 +221,7 @@ Summary: Using Visual Studio Code, update the necessary files to add the next re ``` Next: Create placeholder files to prep for vNext release notes and TPSRs. + ### **Part 4: Prepare new release files** Summary: Using Visual Studio Code, create placeholder files for the next release's release notes and TPSRs. Finish the staging process by merging your PR in GitHub. From 388f7d2688324ec3c763814aad8e324839111c92 Mon Sep 17 00:00:00 2001 From: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> Date: Fri, 15 Nov 2024 15:27:11 +0100 Subject: [PATCH 23/67] Update install-zowe-zos-convenience-build.md Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> --- docs/user-guide/install-zowe-zos-convenience-build.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index 39bff3240d..6479e4a4ca 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -140,6 +140,7 @@ Library DDNAME | Member Type | Target Volume | Type | Org | RECFM | LRECL | No. SZWESAMP | Samples | ANY | U | PDSE | FB | 80 | 15 | 5 SZWEAUTH | Zowe APF Load Modules | ANY | U | PDSE | U | 0 | 15 | N/A SZWEEXEC | CLIST copy utilities | ANY | U | PDSE | FB | 80 | 15 | 5 +SZWELOAD | Executable utilities library | ANY | U | PDSE | U | 0 | 15 | N/A The `SZWESAMP` data set contains the following members. @@ -167,6 +168,8 @@ ZWESAUX | Load module for the cross memory server's auxiliary address space The `SZWEEXEC` data set contains few utilities used by Zowe. +The `SZWELOAD` data set contains config manager for REXX. + ### Procedure The high level qualifer (or HLQ) for these data sets is specified in the `zowe.yaml` section below. Ensure that you update the `zowe.setup.dataset.prefix` value to match your system. From 090a4455c4964beaa33bfb18375cc5263bec0f7d Mon Sep 17 00:00:00 2001 From: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> Date: Fri, 15 Nov 2024 16:48:31 +0100 Subject: [PATCH 24/67] Update install-zowe-zos-convenience-build.md Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> --- docs/user-guide/install-zowe-zos-convenience-build.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index 6479e4a4ca..eb8ada603d 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -197,6 +197,7 @@ A sample run of the command is shown below using default values. Create MVS data sets if they are not exist Creating Zowe sample library - IBMUSER.ZWEV2.SZWESAMP Creating Zowe authorized load library - IBMUSER.ZWEV2.SZWEAUTH +Creating Zowe load library - IBMUSER.ZWEV2.SZWELOAD Creating Zowe executable utilities library - IBMUSER.ZWEV2.SZWEEXEC Copy files/SZWESAMP/ZWESIPRG to IBMUSER.ZWEV2.SZWESAMP From 238ecc98f08eb8e956a61fb73abc11000f5c304a Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 18 Nov 2024 10:17:00 +0100 Subject: [PATCH 25/67] minor language and formatting refactor Signed-off-by: Andrew Jandacek --- .../install-zowe-zos-convenience-build.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index eb8ada603d..d3f87d0074 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -52,8 +52,10 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont ``` put .pax ``` + where: - `zowe-V.v.p` is a variable that indicates the name of the PAX file you downloaded. + * `zowe-V.v.p` + is a variable that indicates the name of the PAX file you downloaded. **Note:** When your terminal is connected to z/OS through FTP or SFTP, you can prepend commands with `l` to have them issued against your desktop. To list the contents of a directory on your desktop, type `lls` where `ls` lists contents of a directory on z/OS. @@ -67,9 +69,11 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont pax -ppx -rf .pax ``` - Where _zowe-V.v.p_ is a variable that indicates the name of the PAX file you downloaded. When extracting the Zowe convenience build, you must always include the `-ppx` argument that preserves extended attributes. + where: + * `zowe-V.v.p` + is a variable that indicates the name of the PAX file you downloaded. When extracting the Zowe convenience build, you must always include the `-ppx` argument that preserves extended attributes. - This will expand to a file structure similar to the following one. + This command expands to a file structure similar to the following one: ``` /bin @@ -80,7 +84,7 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont This is the Zowe runtime directory and is referred to as `` throughout this documentation. - **Note:** Zowe version 1 had a script `zowe-install.sh` that created a separate Zowe runtime directory from the expanded contents of the Zowe PAX file. Zowe v2 no longer has this step. **In Zowe v2, the contents of the expanded Zowe PAX file are the Zowe runtime directory.** + **Note:** Zowe version 1 had a script `zowe-install.sh` that created a separate Zowe runtime directory from the expanded contents of the Zowe PAX file. Zowe v2 no longer has this step. **In Zowe v2, and Zowe v3 the contents of the expanded Zowe PAX file are the Zowe runtime directory.** ## Step 3: (Optional) Add the `zwe` command to your PATH @@ -92,7 +96,7 @@ export PATH=${PATH}:/bin `` should be replaced with your real Zowe runtime directory path. This will update the `PATH` for the current shell. To make this update persistent, you can add the line to your `~/.profile` file, or the `~/.bashProfile` file if you are using a bash shell. To make this update system wide, you can update the `/etc/.profile` file. Once the PATH is updated, you can execute the `zwe` command from any USS directory. For the remainder of the documentation when `zwe` command is referenced, it is assumed that it has been added to your `PATH`. -The `zwe` command has built in help that can be retrieved with the `-h` suffix. For example, type `zwe -h` to display all of the supported commands. These are broken down into a number of sub-commands. +The `zwe` command has built in help that can be retrieved with the `-h` suffix. For example, type `zwe -h` to display all of the supported commands. These are broken down into a number of sub-commands: ``` zwe -h @@ -216,4 +220,4 @@ Copy components/zss/LOADLIB/ZWESAUX to IBMUSER.ZWEV2.SZWEAUTH ## Next steps -You successfully installed Zowe from the convenience build! However, before you start Zowe, you must complete several required configurations. Next, go to [Initialize the z/OS system and permissions](initialize-zos-system.md) to initialize your z/OS system for Zowe first. +You successfully installed Zowe from the convenience build! However, before you start Zowe, you must complete several required configurations. The next step is to [Initialize the z/OS system and permissions](initialize-zos-system.md) for Zowe. From 18594a0e8a3f88b2bfc99ffe44afba5780a7182a Mon Sep 17 00:00:00 2001 From: Martin Zeithaml Date: Mon, 18 Nov 2024 12:31:00 +0100 Subject: [PATCH 26/67] Table of members Signed-off-by: Martin Zeithaml --- .../install-zowe-zos-convenience-build.md | 59 ++++++++++++++----- 1 file changed, 45 insertions(+), 14 deletions(-) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index d3f87d0074..ab04419345 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -84,7 +84,7 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont This is the Zowe runtime directory and is referred to as `` throughout this documentation. - **Note:** Zowe version 1 had a script `zowe-install.sh` that created a separate Zowe runtime directory from the expanded contents of the Zowe PAX file. Zowe v2 no longer has this step. **In Zowe v2, and Zowe v3 the contents of the expanded Zowe PAX file are the Zowe runtime directory.** + **Note:** In Zowe v2, and Zowe v3 the contents of the expanded Zowe PAX file are the Zowe runtime directory. ## Step 3: (Optional) Add the `zwe` command to your PATH @@ -148,19 +148,49 @@ SZWELOAD | Executable utilities library | ANY | U | PDSE | U | 0 | 15 | N/A The `SZWESAMP` data set contains the following members. -Member name | Purpose ----|--- -ZWESECUR | JCL member to configure z/OS user IDs and permissions required to run Zowe -ZWENOSEC | JCL member to undo the configuration steps performed in ZWESECUR and revert z/OS environment changes. -ZWEKRING | JCL member to configure a z/OS keyring containing the Zowe certificate -ZWENOKYR | JCL member to undo the configuration steps performed in ZWEKRING -ZWESLSTC | JCL to start Zowe -ZWEXMSTC | JCL to start the Zowe cross memory server -ZWESIP00 | Parmlib member for the cross memory server -ZWESASTC | Started task JCL for the cross memory Auxiliary server -ZWESIPRG | Console commands to APF authorize the cross memory server load library -ZWESISCH | PPT entries required by Cross memory server and its Auxiliary address spaces to run in Key(4) -ZWECSVSM | JCL Member to create the VSAM data set for the caching service +Member name | Type | Purpose +---|---|--- +ZWECSRVS | JCL | Removes the VSAM data set for the Caching Service +ZWECSVSM | JCL | Creates the VSAM data set for the Caching Service +ZWEGENER | JCL | Generates JCL templates to configure Zowe +ZWEIACF | JCL | Defines security permits for ACF2 +ZWEIACFZ | JCL | Creates the ACF2 Zowe resource class +ZWEIAPF | JCL | Set APF for the required datasets +ZWEIAPF2| JCL | Set APF for the required datasets +ZWEIKRA1 | JCL | Defines ACF2 key ring and certificates +ZWEIKRA2 | JCL | Defines ACF2 key ring and certificates +ZWEIKRA3 | JCL | Defines ACF2 key ring and certificates +ZWEIKRR1 | JCL | Defines RACF key ring and certificates +ZWEIKRR2 | JCL | Defines RACF key ring and certificates +ZWEIKRR3 | JCL | Defines RACF key ring and certificates +ZWEIKRT1 | JCL | Defines TSS key ring and certificates +ZWEIKRT2 | JCL | Defines TSS key ring and certificates +ZWEIKRT3 | JCL | Defines TSS key ring and certificates +ZWEIMVS | JCL | Creates datasets used by a Zowe instance +ZWEIMVS2 | JCL | Creates the load library (expected to be APF) +ZWEINSTL | JCL | Creates and copies basic installation datasets and members +ZWEIRAC | JCL | Defines security permits for RACF +ZWEIRACZ | JCL | Creates the RACF Zowe resource class +ZWEISTC | JCL | Adds `PROCLIB` members +ZWEITSS | JCL | Defines security permits for TSS +ZWEITSSZ | JCL | Creates the TSS Zowe resource class +ZWEKRING | JCL | Defines key ring and certificates +ZWENOKRA | JCL | Removes key ring and certificates for ACF2 +ZWENOKRR | JCL | Removes key ring and certificates for RACF +ZWENOKRT | JCL | Removes key ring and certificates for TSS +ZWENOKYR | JCL | Removes key ring and certificates +ZWENOSEC | JCL | Defines security permits +ZWERMVS | JCL | Removes datasets used by a Zowe instance +ZWERMVS2 | JCL | Removes the APF load library +ZWERSTC | JCL | Removes `PROCLIB` members +ZWESASTC | JCL | Starts the Zowe Auxiliary server used by Cross memory server +ZWESECKG | JCL | Sample program which generates a secret key for the PKCS#11 token +ZWESECUR | JCL | Defines security permits for Zowe +ZWESIPRG | Commands | Console commands to APF authorize the cross memory server load library +ZWESIP00 | PARMLIB | Member for the cross memory server +ZWESISCH | PPT | Defines entries required by Cross memory server and its Auxiliary address spaces to run in Key(4) +ZWESISTC | JCL | Starts the Zowe Cross memory server +ZWESLSTC | JCL | Starts the Zowe The `SZWEAUTH` data set is a load library containing the following members. @@ -169,6 +199,7 @@ Member name | Purpose ZWELNCH | The Zowe launcher that controls the startup, restart and shutdown of Zowe's address spaces ZWESIS01 | Load module for the cross memory server ZWESAUX | Load module for the cross memory server's auxiliary address space +ZWESISDL | ZIS Dynamic Plug-in The `SZWEEXEC` data set contains few utilities used by Zowe. From 95d090a4f3fdb481a036b7e3c236f84429172abb Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 18 Nov 2024 14:57:13 +0100 Subject: [PATCH 27/67] add tip for apfauth and links to reference section Signed-off-by: Andrew Jandacek --- docs/user-guide/configure-zos-system.md | 10 ++-- docs/user-guide/configuring-security.md | 12 ++++- docs/user-guide/initialize-zos-system.md | 4 +- .../zwe-init-subcommand-overview.md | 46 +++++++++++++++++-- 4 files changed, 58 insertions(+), 14 deletions(-) diff --git a/docs/user-guide/configure-zos-system.md b/docs/user-guide/configure-zos-system.md index 72b75372cc..b99daa75ed 100644 --- a/docs/user-guide/configure-zos-system.md +++ b/docs/user-guide/configure-zos-system.md @@ -42,16 +42,16 @@ Be sure your z/OS system meets the following prerequisites: | Set the names for the different z/OS UNIX address spaces for the Zowe runtime components.
**Important:** This configuration step is required. | All components | [Configure address space job naming](#configure-address-space-job-naming) | | To use Zowe desktop. This step generates random numbers for zssServer that the Zowe desktop uses. | Application Framework | [Configure an ICSF cryptographic services environment](#configure-an-icsf-cryptographic-services-environment) | | To allow users to log on to the Zowe desktop through impersonation. | Application Framework | [Configure security environment switching](#configure-security-environment-switching) | -| Required for TSS only. A TSS FACILITY needs to be defined and assigned to the `ZWESLSTC` started task. | ? | [Configure multi-user address space for TSS only](#configure-multi-user-address-space-for-tss-only) | -| Required to manually create the user ID and groups in your z/OS environment. Tasks are performed as part of [Zowe runtime configuration](./configure-zowe-runtime.md) | ? | [Configure user IDs and groups for the Zowe started tasks](#configure-user-ids-and-groups-for-the-zowe-started-tasks) | -| Required to configure the started task ZWESLSTC to run under the correct user ID and group. Tasks are performed as part of [Zowe runtime configuration](./configure-zowe-runtime.md).| ? | [Configure ZWESLSTC to run Zowe high availability instances under ZWESVUSR user ID](#configure-zweslstc-to-run-zowe-high-availability-instances-under-zwesvusr-user-id). | +| Required for TSS only. A TSS FACILITY needs to be defined and assigned to the `ZWESLSTC` started task. | All components | [Configure multi-user address space for TSS only](#configure-multi-user-address-space-for-tss-only) | +| Required to manually create the user ID and groups in your z/OS environment. Tasks are performed as part of [Zowe runtime configuration](./configure-zowe-runtime.md) | All components | [Configure user IDs and groups for the Zowe started tasks](#configure-user-ids-and-groups-for-the-zowe-started-tasks) | +| Required to configure the started task ZWESLSTC to run under the correct user ID and group. Tasks are performed as part of [Zowe runtime configuration](./configure-zowe-runtime.md).| All components | [Configure ZWESLSTC to run Zowe high availability instances under ZWESVUSR user ID](#configure-zweslstc-to-run-zowe-high-availability-instances-under-zwesvusr-user-id). | | Required to configure the cross memory server for SAF to guard against access by non-privileged clients. Tasks are performed as part of [Zowe runtime configuration](./configure-zowe-runtime.md).| Application Framework | [Configure the cross memory server for SAF](#configure-the-cross-memory-server-for-saf) | | Required for API Mediation Layer to map a client certificate to a z/OS identity. | API ML | [Configure main Zowe server to use client certificate identity mapping](#configure-main-zowe-server-to-use-client-certificate-identity-mapping) | | Required for API ML to map the association between a z/OS user ID and a distributed user identity. | API ML | [Configure main Zowe server to use distributed identity mapping](#configure-main-zowe-server-to-use-distributed-identity-mapping) | | To configure SAF Identity tokens on z/OS so that they can be used by Zowe components like zss or API Mediation Layer. | Application Framework
API ML | [Configure signed SAF Identity tokens IDT](#configure-signed-saf-identity-tokens-idt) | | Required for API Mediation Layer to issue SMF records. | API ML | [Configure the main Zowe server to issue SMF records](api-mediation/api-mediation-smf.md#configure-the-main-zowe-server-to-issue-smf-records) | -| To use multi-factor authentication (MFA) | ? | [Multi-Factor Authentication (MFA)](#multi-factor-authentication-mfa) | -| To use Single Sign-On (SSO) | ? | [Single Sign-On (SSO)](#single-sign-on-sso) | +| To use multi-factor authentication (MFA) | All components | [Multi-Factor Authentication (MFA)](#multi-factor-authentication-mfa) | +| To use Single Sign-On (SSO) | All components | [Single Sign-On (SSO)](#single-sign-on-sso) | | To use OIDC Authentication with API Mediation Layer | API ML | [API Mediation Layer OIDC Authentication](#api-mediation-layer-oidc-authentication) | ### Configure address space job naming diff --git a/docs/user-guide/configuring-security.md b/docs/user-guide/configuring-security.md index d0113aefe7..0302df491c 100644 --- a/docs/user-guide/configuring-security.md +++ b/docs/user-guide/configuring-security.md @@ -2,7 +2,7 @@ During the initial installation of Zowe server-side components, it is necessary for your organization's security administrator to perform a range of tasks that require elevated security permissions. As a security administrator, follow the procedures outlined in this article to configure Zowe and your z/OS system to run Zowe with z/OS. -:::info Required roles: system programmer, security administrator +:::info Required role: security administrator (elevated permissions required) ::: :::note @@ -88,8 +88,12 @@ The following video shows how to locate the `ZWESECUR` JCL member and execute it
+:::tip + +If an error occured in performing security configuration, these configurations can be undone. +
+Click here for details about undoing security configurations. -### Undo security configurations To undo all of the z/OS security configuration steps performed by the JCL member `ZWESECUR`, use the reverse member `ZWENOSEC`. This member contains steps that reverse steps performed by `ZWESECUR`. This is useful in the following situations: @@ -98,6 +102,10 @@ To undo all of the z/OS security configuration steps performed by the JCL member If you run `ZWENOSEC` on a z/OS system, it is necessary to rerun `ZWESECUR` to reinitialize the z/OS security configuration. Zowe cannot be run until `ZWESECUR` is rerun. +
+ +::: + ## Perform APF authorization of load libraries Zowe contains load modules that require access to make privileged z/OS security manager calls. These load modules are held in two load libraries which must be APF authorized. For more information about how to issue the `zwe init apfauth` command to perform APF authority commands, see [Performing APF authorization of load libraries](./apf-authorize-load-library.md). diff --git a/docs/user-guide/initialize-zos-system.md b/docs/user-guide/initialize-zos-system.md index c96f599fe9..0d992d9a3b 100644 --- a/docs/user-guide/initialize-zos-system.md +++ b/docs/user-guide/initialize-zos-system.md @@ -23,10 +23,8 @@ Configures the system to launch the Zowe started task. Configures the VSAM files needed if the Caching service is set to VSAM mode. This is not required nor the default, and exists for compatibility. :::info Recommendation: -We recommend you to run these sub commands one by one to clearly see the output of each step. To successfully run `zwe init security`, `zwe init apfauth`, and `zwe init certificate`, it is likely that your organization requires elevated permissions. We recommend you consult with your security administrator to run these commands. For more information about tasks for the security administrator, see the section [Configuring security](./configuring-security.md) in this configuration documentation. +We recommend you to run these sub commands one by one to clearly see the output of each step. To successfully run `zwe init security`, `zwe init apfauth`, and `zwe init certificate`, it is likely that your organization requires elevated permissions. We recommend you consult with your security administrator to run these commands. For more information about tasks for the security administrator, and details about the `zwe init security` command, see the section [Configuring security](./configuring-security.md) in this configuration documentation - -For information about the `zwe init security` command, see [configuring with `zwe init security` command](./initialize-security-configuration.md#configuring-with-zwe-init-security-command). ::: :::tip diff --git a/docs/user-guide/zwe-init-subcommand-overview.md b/docs/user-guide/zwe-init-subcommand-overview.md index 44a6164100..97aae1cdb0 100644 --- a/docs/user-guide/zwe-init-subcommand-overview.md +++ b/docs/user-guide/zwe-init-subcommand-overview.md @@ -112,11 +112,14 @@ If Zowe has already been launched on a z/OS system from a previous release of Zo The JCL member `.SZWESAMP(ZWESECUR)` is provided to assist with the security configuration. Before submitting the `ZWESECUR` JCL member, customize this member to match site security rules. For script driven scenarios, you can run the command `zwe init security` which uses `ZWESECUR` as a template to create a customized member in `.CUST.JCLLIB`. This member contains the commands required to perform the security configuration. -For more information about `zwe init security`, see _Configure with `zwe init security` command_ in [Configuring security](./configuring-security.md). +For more information about `zwe init security`, see: + +* _Configure with `zwe init security` command_ in [Configuring security](./configuring-security.md). +* [`zwe init security`](../appendix/zwe_server_command_reference/zwe/init/zwe-init-security.md) in the Reference section. :::tip -To avoid having to run the `init security` command, you can specify the parameter `--security-dry-run`. This parameter enables you to construct a JCL member containing the security commmands without running the member. This is useful for previewing commands and can also be used to copy and paste commands into a TSO command prompt for step by step manual execution. +To avoid having to run the `init security` command, you can specify the flag `--security-dry-run`. This flag enables you to construct a JCL member containing the security commmands without running the member. This is useful for previewing commands and can also be used to copy and paste commands into a TSO command prompt for step by step manual execution. **Example:** @@ -153,7 +156,40 @@ Specifies the user custom load library, containing the ZWELNCH, ZWESIS01 and ZWE * **zowe.setup.dataset.authPluginLib** References the load library for ZIS plugins. -For more information about `zwe init apfauth` see [Performing APF authorization of load libraries](./apf-authorize-load-library). +For more information about `zwe init apfauth` see: +* [Performing APF authorization of load libraries](./apf-authorize-load-library). +* [`zwe init apfauth`](../appendix/zwe_server_command_reference/zwe/init/zwe-init-apfauth.md) in the Reference section. + +:::tip + +To avoid having to run the `init apfauth` command, you can specify the flag `--security-dry-run` as in the following example. + +**Example:** + +``` +zwe init apfauth --security-dry-run -c /path/to/zowe.yaml +------------------------------------------------------------------------------- +>> APF authorize load libraries + +APF authorize IBMUSER.ZWEV2.SZWEAUTH +- Dry-run mode, security setup is NOT performed on the system. + Please apply this operator command manually: + + SETPROG APF,ADD,DSNAME=IBMUSER.ZWEV2.SZWEAUTH,SMS + +APF authorize IBMUSER.ZWEV2.CUST.ZWESAPL +- Dry-run mode, security setup is NOT performed on the system. + Please apply this operator command manually: + + SETPROG APF,ADD,DSNAME=IBMUSER.ZWEV2.CUST.ZWESAPL,SMS + + +>> Zowe load libraries are APF authorized successfully. + +``` +For production environments, inform your security administrator to re-submit the `init apfauth` command with proper authorization. + +::: ## Configuring Zowe to use TLS certificates (`zwe init certificate`) @@ -164,7 +200,9 @@ Zowe uses digital certificates for secure, encrypted network communication over Zowe supports using either file-based (PKCS12) or z/OS key ring-based (when on z/OS) keystores and truststores, and can reuse compatible stores. You can use the `zwe init certificate` command to create keystores and truststores by either generating certificates or by allowing users to import their own compatible certificates. -For more information, see [Configuring certificates](./configure-certificates). +For more information about `init certificate`, see: +* [Configuring certificates](./configure-certificates). +* [`zwe init certificate`](../appendix/zwe_server_command_reference/zwe/init/zwe-init-certificate.md) in the Reference section. ## Installing Zowe main started tasks (`zwe init stc`) From 5ef0f29987057bf34f91b886a5c3940ab597df2b Mon Sep 17 00:00:00 2001 From: Martin Zeithaml Date: Mon, 18 Nov 2024 15:13:31 +0100 Subject: [PATCH 28/67] Minor changes Signed-off-by: Martin Zeithaml --- .../install-zowe-zos-convenience-build.md | 40 ++++++++++++------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index ab04419345..08f23a83ad 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -17,7 +17,7 @@ Complete the following steps to install the Zowe runtime. ## Step 1: Obtain the convenience build 1. To download the PAX file, open your web browser on the [Zowe Download](https://www.zowe.org/download.html) website. -2. Navigate to **Zowe V2 Preview** -> **Convenience build** section, and select the button to download the v2 convenience build. +2. Navigate to **Zowe V3** -> **Zowe 3.v.p z/OS Convenience build** section, and select the button to download the v3 convenience build. ## Step 2: Transfer the convenience build to USS and expand it @@ -59,6 +59,12 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont **Note:** When your terminal is connected to z/OS through FTP or SFTP, you can prepend commands with `l` to have them issued against your desktop. To list the contents of a directory on your desktop, type `lls` where `ls` lists contents of a directory on z/OS. + :::tip + You can simplify `sftp` usage for existing directory: + ``` + echo 'put .pax' | sftp userID@ip.of.zos.box:/path/to/zowe/runtime + ``` + After the PAX file has sucessfully transferred, exit your `sftp` or `ftp` session. 1. Open a USS shell to expand the PAX file. This can either be an ssh terminal, OMVS, iShell, or any other z/OS unix system services command environment. @@ -94,23 +100,27 @@ The `zwe` command is provided in the `/bin` directory. You can opti export PATH=${PATH}:/bin ``` -`` should be replaced with your real Zowe runtime directory path. This will update the `PATH` for the current shell. To make this update persistent, you can add the line to your `~/.profile` file, or the `~/.bashProfile` file if you are using a bash shell. To make this update system wide, you can update the `/etc/.profile` file. Once the PATH is updated, you can execute the `zwe` command from any USS directory. For the remainder of the documentation when `zwe` command is referenced, it is assumed that it has been added to your `PATH`. +`` should be replaced with your real Zowe runtime directory path. This will update the `PATH` for the current shell. To make this update persistent, you can add the line to your `~/.profile` file, or the `~/.bashProfile` file if you are using a bash shell. To make this update system wide, you can update the `/etc/.profile` file. Once the `PATH` is updated, you can execute the `zwe` command from any USS directory. For the remainder of the documentation when `zwe` command is referenced, it is assumed that it has been added to your `PATH`. -The `zwe` command has built in help that can be retrieved with the `-h` suffix. For example, type `zwe -h` to display all of the supported commands. These are broken down into a number of sub-commands: +The `zwe` command has built in help that can be retrieved with the `-h` option. For example, type `zwe -h` to display all of the supported commands. These are broken down into a number of sub-commands: ``` zwe -h ... Available sub-command(s): - - certificate - - components - - init - - install - - internal - - sample - - start - - stop - - version + - certificate + - components + - config + - diagnose + - init + - install + - internal + - migrate + - sample + - start + - stop + - support + - version ``` ## Step 4: Copy the zowe.yaml configuration file to preferred location @@ -120,7 +130,7 @@ Copy the template file `/example-zowe.yaml` file to a new location, When you execute the `zwe` command, the `-c` argument is used to pass the location of a `zowe.yaml` file. :::tip -To avoid passing `--config` or `-c` to every `zwe` commands, you can define `ZWE_CLI_PARAMETER_CONFIG` environment variable points to location of zowe.yaml. +To avoid passing `--config` or `-c` to every `zwe` commands, you can define `ZWE_CLI_PARAMETER_CONFIG` environment variable pointing to location of `zowe.yaml`. For example, after defining @@ -137,7 +147,7 @@ After you extract the Zowe convenience build, you can run the [`zwe install` com ### About the MVS data sets -Zowe includes a number of files that are stored in the following three data sets. See the following table for the storage requirements. +Zowe includes a number of files that are stored in the following data sets. See the following table for the storage requirements. Library DDNAME | Member Type | Target Volume | Type | Org | RECFM | LRECL | No. of 3390 Trks | No. of DIR Blks ---|---|---|---|---|---|---|---|--- @@ -218,7 +228,7 @@ zowe: ``` To create and install the MVS data sets, use the command `zwe install`. -1. In a USS shell, execute the command `zwe install -c /path/to/zowe.yaml`. This creates the three data sets and copy across their content. +1. In a USS shell, execute the command `zwe install -c /path/to/zowe.yaml`. This creates the data sets and copy across their content. 2. If the data sets already exist, specify `--allow-overwritten`. 3. To see the full list of parameters, execute the command `zwe install -h`. From b8f7c931a43b9d64a4077f7cd0642145f832f758 Mon Sep 17 00:00:00 2001 From: Martin Zeithaml Date: Mon, 18 Nov 2024 15:16:11 +0100 Subject: [PATCH 29/67] Indentation update Signed-off-by: Martin Zeithaml --- .../install-zowe-zos-convenience-build.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index 08f23a83ad..d8cbf32d31 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -108,19 +108,19 @@ The `zwe` command has built in help that can be retrieved with the `-h` option. zwe -h ... Available sub-command(s): - - certificate - - components - - config - - diagnose - - init - - install - - internal - - migrate - - sample - - start - - stop - - support - - version + - certificate + - components + - config + - diagnose + - init + - install + - internal + - migrate + - sample + - start + - stop + - support + - version ``` ## Step 4: Copy the zowe.yaml configuration file to preferred location From 55025cbb162aaa974207e78d4b224c98723d2cac Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 18 Nov 2024 16:41:01 +0100 Subject: [PATCH 30/67] change title of Customization of z/OS system Signed-off-by: Andrew Jandacek --- docs/user-guide/configure-zos-system.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/configure-zos-system.md b/docs/user-guide/configure-zos-system.md index b99daa75ed..0eb5044faf 100644 --- a/docs/user-guide/configure-zos-system.md +++ b/docs/user-guide/configure-zos-system.md @@ -1,4 +1,4 @@ -# Security customization of your z/OS system +# Customizing z/OS system security As a security administrator, configure your z/OS system according to the specific features and functionalities you choose to include in your Zowe installation. Review the following article for specific configuration steps that apply to these features and fuctionalities. @@ -10,7 +10,7 @@ As a security administrator, configure your z/OS system according to the specifi Before performing configuration steps specific to your use case, ensure that you meet the z/OS system requirements presented in the section _Preparing for installation_. For detailed information, see [Addressing z/OS requirements](./systemrequirements-zos.md). ::: - - To work with USS, this user ID must have a valid OMVS segment. For more information about OMVS segments, see the - article _The OMVS segment in user profiles_ in the IBM documentation. For detailed information about which permissions - are - required to run Zowe core services as well as specific individual components, see - the [Security Permissions Reference Table](#security-permissions-reference-table) in this article. + components. + * **ZWESIUSR** This user runs the cross memory server (ZIS). This is a started task ID used to run the PROCLIB `ZWESISTC` that - launches the [cross memory server (ZIS)](./configure-xmem-server.md). This started task ID must have a valid OMVS - segment. + launches the [cross memory server (ZIS)](./configure-xmem-server.md). + +:::caution Important! +To work with USS, the user ID must have a valid OMVS segment. For more information about OMVS segments, see the article _The OMVS segment in user profiles_ in the IBM documentation. For detailed information about which permissions are required to run Zowe core services as well as specific individual components, see the [Security Permissions Reference Table](#security-permissions-reference-table) in this article. + +::: The security administrator also assigns permissions to the security group **ZWEADMIN**. `ZWEADMIN` is a group consisting of `ZWESVUSR` and `ZWESIUSR`. This group must have a valid OMVS segment. @@ -92,12 +92,20 @@ You can skip this section if you use Zowe without z/OSMF. Zowe can operate with To grant permissions to the user ID to access z/OSMF, issue the command(s) that corresponds to your ESM. +
+Click here for command details for RACF. + - If you use RACF, issue the following command: ``` CONNECT (userid) GROUP(IZUUSER) ``` +
+ +
+Click here for command details for ACF2. + - If you use ACF2, issue the following commands: ``` @@ -105,12 +113,18 @@ To grant permissions to the user ID to access z/OSMF, issue the command(s) that F ACF2,REBUILD(TGR) ``` +
+ +
+Click here for command details for Top Secret. + - If you use Top Secret, issue the following commands: ``` TSS ADD(userid) PROFILE(IZUUSER) TSS ADD(userid) GROUP(IZUUSRGP) ``` +
## Next step diff --git a/docs/user-guide/configure-zos-system.md b/docs/user-guide/configure-zos-system.md index e0eaece83e..372e67b9f7 100644 --- a/docs/user-guide/configure-zos-system.md +++ b/docs/user-guide/configure-zos-system.md @@ -56,7 +56,7 @@ Be sure your z/OS system meets the following prerequisites: ### Configure address space job naming -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. +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. :::note This procedure may require security administrator authorization. Consult with your security administrator. @@ -386,7 +386,7 @@ F ACF2,REBUILD(APL) ### Configure address space job naming -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. +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. :::note This procedure may require security administrator authorization. Consult with your security administrator. @@ -491,7 +491,7 @@ If you have not run `ZWESECUR` and are manually creating the user ID and groups
- * To create the `ZWESVUSR` user ID for the main Zowe started task, issue the following command: + * To create the `ZWESVUSR` user ID for the main Zowe started task, issue the following command according to your ESM:
@@ -536,7 +536,7 @@ If you have not run `ZWESECUR` and are manually creating the user ID and groups ```
-- To create the `ZWESIUSR` group for the Zowe cross memory server started task, issue the following command: +- To create the `ZWESIUSR` group for the Zowe cross memory server started task, issue the following command according to your ESM:
Click here for command details for RACF. @@ -591,7 +591,7 @@ If you have run `ZWESECUR`, you do not need to perform the steps described in th ... ``` -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 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. Issue the following commands according to your ESM:
Click here for command details for RACF. @@ -718,7 +718,7 @@ If you use Top Secret, issue the following commands, where `owner-acid` can be I ### Configure main Zowe server to use client certificate identity mapping -This security configuration is necessary for API ML to be able to map client certificate to a z/OS identity. A user running API Gateway must have read access to the SAF resource `IRR.RUSERMAP` in the `FACILITY` class. +This security configuration is necessary for API ML to be able to map client certificate to a z/OS identity. A user running API Gateway must have READ access to the SAF resource `IRR.RUSERMAP` in the `FACILITY` class. To set up this security configuration, submit the `ZWESECUR` JCL member. For users upgrading from version 1.18 and lower use the following configuration steps according to your ESM:
@@ -728,12 +728,12 @@ If you use RACF, verify and update permission in the `FACILITY` class. **Follow these steps:** -1. Verify user `ZWESVUSR` has read access. +1. Verify user `ZWESVUSR` has READ access. ``` RLIST FACILITY IRR.RUSERMAP AUTHUSER ``` -2. Add user `ZWESVUSR` permission to read. +2. Add user `ZWESVUSR` permission to READ. ``` PERMIT IRR.RUSERMAP CLASS(FACILITY) ACCESS(READ) ID(ZWESVUSR) ``` @@ -752,13 +752,13 @@ If you use ACF2, verify and update permission in the `FACILITY` class. **Follow these steps:** -1. Verify user `ZWESVUSR` has read access. +1. Verify user `ZWESVUSR` has READ access. ``` SET RESOURCE(FAC) LIST LIKE(IRR-) ``` -2. Add user `ZWESVUSR` permission to read. +2. Add user `ZWESVUSR` permission to READ. ``` RECKEY IRR.RUSERMAP ADD(SERVICE(READ) ROLE(&STCGRP.) ALLOW) ``` @@ -777,11 +777,11 @@ If you use TSS, verify and update permission in `FACILITY` class. **Follow these steps:** -1. Verify user `ZWESVUSR` has read access. +1. Verify user `ZWESVUSR` has READ access. ``` TSS WHOHAS IBMFAC(IRR.RUSERMAP) ``` -2. Add user `ZWESVUSR` permission to read. +2. Add user `ZWESVUSR` permission to READ. ``` TSS PER(ZWESVUSR) IBMFAC(IRR.RUSERMAP) ACCESS(READ) ``` @@ -800,7 +800,7 @@ If you use RACF, verify and update permission in the `FACILITY` class. **Follow these steps:** -1. Verify that user `ZWESVUSR` has read access. +1. Verify that user `ZWESVUSR` has READ access. ``` RLIST FACILITY IRR.IDIDMAP.QUERY AUTHUSER ``` diff --git a/docs/user-guide/configuring-security.md b/docs/user-guide/configuring-security.md index 0302df491c..aa84dfe5d2 100644 --- a/docs/user-guide/configuring-security.md +++ b/docs/user-guide/configuring-security.md @@ -112,11 +112,11 @@ Zowe contains load modules that require access to make privileged z/OS security ## Customize security of your z/OS system -Review and perform z/OS configuration steps based on your settings. For a detailed table of configuration procedures and associated purposes for performing these procedures, see [Security customization of your z/OS system](./configure-zos-system.md). +Review and perform z/OS configuration steps based on your settings. For a detailed table of configuration procedures and associated purposes for performing these procedures, see [Customizing z/OS system security](./configure-zos-system.md). ## Assign security permissions to users -Assign users (ZWESVUSR and ZWESIUSR) and the ZWEADMIN security group permissions required to perform specific tasks. For more information see, [Assign security permissions to users](./assign-security-permissions-to-users.md). +Assign users (ZWESVUSR and ZWESIUSR) and the ZWEADMIN security group permissions required to perform specific tasks. For more information see, [Assigning security permissions to users](./assign-security-permissions-to-users.md). ## Zowe Feature specific configuration tasks From 0b2d38bc412ccadfba6a71991867d46a8ea8e90d Mon Sep 17 00:00:00 2001 From: Martin Zeithaml Date: Tue, 19 Nov 2024 12:56:00 +0100 Subject: [PATCH 36/67] Minor updates Signed-off-by: Martin Zeithaml --- docs/user-guide/install-zowe-zos-convenience-build.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index d8cbf32d31..e45cb1d15d 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -64,6 +64,7 @@ After you download the PAX file, you can transfer it to z/OS and expand its cont ``` echo 'put .pax' | sftp userID@ip.of.zos.box:/path/to/zowe/runtime ``` + ::: After the PAX file has sucessfully transferred, exit your `sftp` or `ftp` session. @@ -147,7 +148,7 @@ After you extract the Zowe convenience build, you can run the [`zwe install` com ### About the MVS data sets -Zowe includes a number of files that are stored in the following data sets. See the following table for the storage requirements. +Zowe includes a number of files that are stored in the various data sets. See the following table for the storage requirements. Library DDNAME | Member Type | Target Volume | Type | Org | RECFM | LRECL | No. of 3390 Trks | No. of DIR Blks ---|---|---|---|---|---|---|---|--- From 99a0c05b52b96e8a1b954838b0101bfa1c015616 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Tue, 19 Nov 2024 13:49:48 +0100 Subject: [PATCH 37/67] fix caching service properties, add deprecations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../api-mediation-caching-service.md | 10 +- .../configure-caching-service-ha.md | 133 +++++++++--------- .../api-mediation-caching-service.md | 4 +- .../configure-caching-service-ha.md | 133 +++++++++--------- 4 files changed, 148 insertions(+), 132 deletions(-) diff --git a/docs/user-guide/api-mediation/api-mediation-caching-service.md b/docs/user-guide/api-mediation/api-mediation-caching-service.md index 501c3c52d6..aa1cc5cbe9 100644 --- a/docs/user-guide/api-mediation/api-mediation-caching-service.md +++ b/docs/user-guide/api-mediation/api-mediation-caching-service.md @@ -31,12 +31,14 @@ A precondition to provide for High Availability of all components within Zowe is REST APIs make it possible to create, delete, and update key-value pairs in the cache. Other APIs read a specific key-value pair or all key-value pairs in the cache. Information from cached APIs is stored as a JSON in the following format: + ```yml { “key”: “keyValue”, “value”: “valueValue” } ``` + ## Storage methods The Caching Service supports the following storage solutions, which provide the option to add custom implementation. @@ -63,8 +65,8 @@ For more information about the Redis storage access method, see [Using Redis as ### InMemory -The InMemory storage method is a method suitable for testing and integration verification. Be sure not to use InMemory storage in production. -The key/value pairs are stored only in the memory of a single instance of the service. As such, the key/value pairs do not persist. +The InMemory storage method is a method suitable for testing and integration verification. Be sure not to use InMemory storage in production. +The key/value pairs are stored only in the memory of a single instance of the service. As such, the key/value pairs do not persist. ## How to start the Service @@ -122,11 +124,13 @@ This parameter specifies service behavior when the limit of records is reached. ## Authentication ### Direct calls + The Caching Service requires TLS mutual authentication. This verifies authenticity of the client. Calls without a valid client certificate generate a `403` response code: `Forbidden`. This requirement is disabled when `VERIFY_CERTIFICATES=false` in `zowe-certificates.env` configuration file. -The call must have a header `X-Certificate-DistinguishedName` containing information about the certificate's distinguished name. This header is added by the API Gateway. For a direct call, this header needs to be added manually. Calls without this header produce a `401` response code: `Unauthorized`. +The call must have a header `X-Certificate-DistinguishedName` containing information about the certificate's distinguished name. This header is added by the API Gateway. For a direct call, this header needs to be added manually. Calls without this header produce a `401` response code: `Unauthorized`. ### Routed calls through API Gateway + Caching service registers with the following authentication scheme to Discovery service: ```yaml diff --git a/docs/user-guide/configure-caching-service-ha.md b/docs/user-guide/configure-caching-service-ha.md index b9566ece2b..40e1f1a584 100644 --- a/docs/user-guide/configure-caching-service-ha.md +++ b/docs/user-guide/configure-caching-service-ha.md @@ -2,54 +2,63 @@ Zowe can work in a high availability (HA) configuration where multiple instances of the Zowe launcher are started, either on the same LPAR, or different LPARs connected through sysplex distributor. If you are only running a single Zowe instance on a single LPAR you do not need to create a caching service so you may skip this step. -In an HA setup the different Zowe API Mediation Gateway servers share the same northbound port (by default `7554`), and client traffic to this port is distributed between separate gateways that in turn dispatch their work to different services. When any of the services individually become unavailable the work can be routed to available services, which means that the initial northbound request will be fulfilled. +In an HA setup the different Zowe API Mediation Gateway servers share the same northbound port (by default `7554`), and client traffic to this port is distributed between separate gateways that in turn dispatch their work to different services. When any of the services individually become unavailable the work can be routed to available services, which means that the initial northbound request will be fulfilled. -Zowe uses the Caching Service to centralize the state data persistent in high availability (HA) mode. If you are runnning the caching service on z/OS there are three storage methods: `inMemory`, `infinispan` or `VSAM`. If you are running the caching service off platform, such as a Linux or Windows container image, it is also possible to specify `redis` or `infinispan`. +Zowe uses the Caching Service to centralize the state data persistent in high availability (HA) mode. If you are runnning the caching service on z/OS there are three storage methods: `inMemory`, `infinispan` or `VSAM`. If you are running the caching service off platform, such as a Linux or Windows container image, it is also possible to specify `redis` or `infinispan`. -To learn more about how the Caching Service can be used, see [Using the Caching Service](../user-guide/api-mediation/api-mediation-caching-service). +To learn more about how the Caching Service can be used, see [Using the Caching Service](../user-guide/api-mediation/api-mediation-caching-service). :::note To enable Personal Access Token support when using the Caching Service, **Infinispan** is the required storage solution. Infinispan is part of Zowe installation. No additional software or installation is required when using this storage solution. Infinispan is the recommended storage method to use in production. ::: ## 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, set the `zowe.components.caching-service.storage.mode` value to `inMemory` in the `zowe.yaml` configuration file. When this method is enabled, the Caching Service will not persist any data. + To use this method, set the `components.caching-service.storage.mode` value to `inMemory` in the `zowe.yaml` configuration file. When this method is enabled, the Caching Service will not persist any data. ``` yaml - zowe - components: - caching-service: - enabled: true - port: 7555 - storage: - evictionStrategy: reject - mode: imMemory - size: 10000 + components: + caching-service: + enabled: true + port: 7555 + storage: + evictionStrategy: reject + mode: imMemory + size: 10000 ``` ## Infinispan - Infinispan is designed to be run mainly on z/OS since it offers good performance. To enable this method, set the value of `zowe.components.caching-service.storage.mode` to `infinispan` in the `zowe.yaml` configuration file. + :::Note + + This is the recommended solution for on-prem z/OS production deployments + + ::: + + Infinispan is designed to be run mainly on z/OS since it offers good performance. To enable this method, set the value of `components.caching-service.storage.mode` to `infinispan` in the `zowe.yaml` configuration file. Infinispan environment variables are not currently following the v2 naming convention, so they must be defined into `zowe.environments` section. For more information on these properties and their values see [Infinispan configuration](../extend/extend-apiml/api-mediation-infinispan.md#infinispan-configuration). ``` yaml - zowe - components: - caching-service: - storage: - mode: infinispan - infinispan: - jgroups: - port: 7098 + components: + caching-service: + storage: + mode: infinispan + infinispan: + jgroups: + port: 7098 ``` -## VSAM - - This storage method allows you tu use VSAM dataset as a storage for Caching service. You can use `zwe init vsam` command to generate proper dataset. +## VSAM (Deprecated) + + :::Note + + VSAM support in Caching Service will be removed in a future release + ::: + + This storage method allows you tu use VSAM dataset as a storage for Caching service. You can use `zwe init vsam` command to generate proper dataset. The command `zwe init vsam` uses the template JCL in `SZWESAMP(ZWECSVSM)`. You can edit and submit this yourself, or else if use `zwe init vsam` which will copy the source template member from `zowe.setup.mvs.hlq.SZWESAMP(ZWECVCSM)` and create a target JCL member in `zowe.setup.mvs.jcllib(ZWECVSCM)` with values extracted from the `zowe.yaml` file. @@ -63,15 +72,15 @@ To enable Personal Access Token support when using the Caching Service, **Infini mode: NONRLS volume: VOL123 storageClass: - components: - caching-service: - storage: - mode: VSAM - vsam: - name: IBMUSER.ZWE.CUST.CACHE + components: + caching-service: + storage: + mode: VSAM + vsam: + name: IBMUSER.ZWE.CUST.CACHE ``` - - `zowe.components.caching-service.storage.vsam.name` + - `components.caching-service.storage.vsam.name` This specifies the data set name that the `ZWECSVSM` JCL will create. This is used to replace all occurrences of `#dsname` in the `ZWECSVSM` data set. :::note @@ -79,20 +88,18 @@ To enable Personal Access Token support when using the Caching Service, **Infini `zowe.environments.CACHING_STORAGE_VSAM_KEYLENGTH` and `zowe.environments.CACHING_STORAGE_VSAM_RECORDLENGTH` must be set to the new values. ::: - - `zowe.components.caching-service.storage.mode` + - `components.caching-service.storage.mode` 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. `NONRLS` is also an allowed value. - - - `zowe.setup.vsam.storageClass` - If you use the `RLS` mode, a storage class is required. + - `zowe.setup.vsam.storageClass` + If you use the `RLS` mode, a storage class is required. - `zowe.setup.vsam.volume` If you set to use the `NONRLS` mode, a storage volume is required. - To preview the member before submitting it, use the value `--security-dry-run`. Otherwise, the command automatically submits the JCL and waits for its completion. - ``` + ```plaintext >zwe init vsam -c ./zowe.yaml ------------------------------------------------------------------------------- >> Create VSAM storage for Zowe Caching Service @@ -104,33 +111,31 @@ To enable Personal Access Token support when using the Caching Service, **Infini > ``` -## redis +## Redis Redis is not available if you are running the API Mediation Layer on z/OS under Unix System Services. Usage of redis is intended for when API ML is running off platform, such as in a Linux or Windows container as part of a hybrid cloud deployment. - To enable this method, set the value of `zowe.components.caching-service.storage.mode` to `redis` in the `zowe.yaml` configuration file. There are a number of values to control the redis nodes, sentinel and ssl properties that need to be set in the `zowe.yaml` file. For more information on these properties and their values see [Redis configuration](../extend/extend-apiml/api-mediation-redis.md#redis-configuration). - - + To enable this method, set the value of `components.caching-service.storage.mode` to `redis` in the `zowe.yaml` configuration file. There are a number of values to control the redis nodes, sentinel and ssl properties that need to be set in the `zowe.yaml` file. For more information on these properties and their values see [Redis configuration](../extend/extend-apiml/api-mediation-redis.md#redis-configuration). + ```yaml - zowe: - components: - caching-service: - enabled: true - port: 7555 - storage: - size: 10000 - evictionStrategy: reject - mode: redis - redis: - masterNodeUri: - timeout: 60 - sentinel: - masterInstance - nodes - ssl: - enabled: true - keystore: - keystorePassword: - trustStore: - trustStorePassword + components: + caching-service: + enabled: true + port: 7555 + storage: + size: 10000 + evictionStrategy: reject + mode: redis + redis: + masterNodeUri: + timeout: 60 + sentinel: + masterInstance + nodes + ssl: + enabled: true + keystore: + keystorePassword: + trustStore: + trustStorePassword ``` diff --git a/versioned_docs/version-v2.18.x/user-guide/api-mediation/api-mediation-caching-service.md b/versioned_docs/version-v2.18.x/user-guide/api-mediation/api-mediation-caching-service.md index 6078edb29d..a9e5223596 100644 --- a/versioned_docs/version-v2.18.x/user-guide/api-mediation/api-mediation-caching-service.md +++ b/versioned_docs/version-v2.18.x/user-guide/api-mediation/api-mediation-caching-service.md @@ -30,12 +30,14 @@ A precondition to provide for High Availability of all components within Zowe is REST APIs make it possible to create, delete, and update key-value pairs in the cache. Other APIs read a specific key-value pair or all key-value pairs in the cache. Information from cached APIs is stored as a JSON in the following format: -```yml + +```yaml { “key”: “keyValue”, “value”: “valueValue” } ``` + ## Storage methods The Caching Service supports the following storage solutions, which provide the option to add custom implementation. diff --git a/versioned_docs/version-v2.18.x/user-guide/configure-caching-service-ha.md b/versioned_docs/version-v2.18.x/user-guide/configure-caching-service-ha.md index b9566ece2b..40e1f1a584 100644 --- a/versioned_docs/version-v2.18.x/user-guide/configure-caching-service-ha.md +++ b/versioned_docs/version-v2.18.x/user-guide/configure-caching-service-ha.md @@ -2,54 +2,63 @@ Zowe can work in a high availability (HA) configuration where multiple instances of the Zowe launcher are started, either on the same LPAR, or different LPARs connected through sysplex distributor. If you are only running a single Zowe instance on a single LPAR you do not need to create a caching service so you may skip this step. -In an HA setup the different Zowe API Mediation Gateway servers share the same northbound port (by default `7554`), and client traffic to this port is distributed between separate gateways that in turn dispatch their work to different services. When any of the services individually become unavailable the work can be routed to available services, which means that the initial northbound request will be fulfilled. +In an HA setup the different Zowe API Mediation Gateway servers share the same northbound port (by default `7554`), and client traffic to this port is distributed between separate gateways that in turn dispatch their work to different services. When any of the services individually become unavailable the work can be routed to available services, which means that the initial northbound request will be fulfilled. -Zowe uses the Caching Service to centralize the state data persistent in high availability (HA) mode. If you are runnning the caching service on z/OS there are three storage methods: `inMemory`, `infinispan` or `VSAM`. If you are running the caching service off platform, such as a Linux or Windows container image, it is also possible to specify `redis` or `infinispan`. +Zowe uses the Caching Service to centralize the state data persistent in high availability (HA) mode. If you are runnning the caching service on z/OS there are three storage methods: `inMemory`, `infinispan` or `VSAM`. If you are running the caching service off platform, such as a Linux or Windows container image, it is also possible to specify `redis` or `infinispan`. -To learn more about how the Caching Service can be used, see [Using the Caching Service](../user-guide/api-mediation/api-mediation-caching-service). +To learn more about how the Caching Service can be used, see [Using the Caching Service](../user-guide/api-mediation/api-mediation-caching-service). :::note To enable Personal Access Token support when using the Caching Service, **Infinispan** is the required storage solution. Infinispan is part of Zowe installation. No additional software or installation is required when using this storage solution. Infinispan is the recommended storage method to use in production. ::: ## 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, set the `zowe.components.caching-service.storage.mode` value to `inMemory` in the `zowe.yaml` configuration file. When this method is enabled, the Caching Service will not persist any data. + To use this method, set the `components.caching-service.storage.mode` value to `inMemory` in the `zowe.yaml` configuration file. When this method is enabled, the Caching Service will not persist any data. ``` yaml - zowe - components: - caching-service: - enabled: true - port: 7555 - storage: - evictionStrategy: reject - mode: imMemory - size: 10000 + components: + caching-service: + enabled: true + port: 7555 + storage: + evictionStrategy: reject + mode: imMemory + size: 10000 ``` ## Infinispan - Infinispan is designed to be run mainly on z/OS since it offers good performance. To enable this method, set the value of `zowe.components.caching-service.storage.mode` to `infinispan` in the `zowe.yaml` configuration file. + :::Note + + This is the recommended solution for on-prem z/OS production deployments + + ::: + + Infinispan is designed to be run mainly on z/OS since it offers good performance. To enable this method, set the value of `components.caching-service.storage.mode` to `infinispan` in the `zowe.yaml` configuration file. Infinispan environment variables are not currently following the v2 naming convention, so they must be defined into `zowe.environments` section. For more information on these properties and their values see [Infinispan configuration](../extend/extend-apiml/api-mediation-infinispan.md#infinispan-configuration). ``` yaml - zowe - components: - caching-service: - storage: - mode: infinispan - infinispan: - jgroups: - port: 7098 + components: + caching-service: + storage: + mode: infinispan + infinispan: + jgroups: + port: 7098 ``` -## VSAM - - This storage method allows you tu use VSAM dataset as a storage for Caching service. You can use `zwe init vsam` command to generate proper dataset. +## VSAM (Deprecated) + + :::Note + + VSAM support in Caching Service will be removed in a future release + ::: + + This storage method allows you tu use VSAM dataset as a storage for Caching service. You can use `zwe init vsam` command to generate proper dataset. The command `zwe init vsam` uses the template JCL in `SZWESAMP(ZWECSVSM)`. You can edit and submit this yourself, or else if use `zwe init vsam` which will copy the source template member from `zowe.setup.mvs.hlq.SZWESAMP(ZWECVCSM)` and create a target JCL member in `zowe.setup.mvs.jcllib(ZWECVSCM)` with values extracted from the `zowe.yaml` file. @@ -63,15 +72,15 @@ To enable Personal Access Token support when using the Caching Service, **Infini mode: NONRLS volume: VOL123 storageClass: - components: - caching-service: - storage: - mode: VSAM - vsam: - name: IBMUSER.ZWE.CUST.CACHE + components: + caching-service: + storage: + mode: VSAM + vsam: + name: IBMUSER.ZWE.CUST.CACHE ``` - - `zowe.components.caching-service.storage.vsam.name` + - `components.caching-service.storage.vsam.name` This specifies the data set name that the `ZWECSVSM` JCL will create. This is used to replace all occurrences of `#dsname` in the `ZWECSVSM` data set. :::note @@ -79,20 +88,18 @@ To enable Personal Access Token support when using the Caching Service, **Infini `zowe.environments.CACHING_STORAGE_VSAM_KEYLENGTH` and `zowe.environments.CACHING_STORAGE_VSAM_RECORDLENGTH` must be set to the new values. ::: - - `zowe.components.caching-service.storage.mode` + - `components.caching-service.storage.mode` 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. `NONRLS` is also an allowed value. - - - `zowe.setup.vsam.storageClass` - If you use the `RLS` mode, a storage class is required. + - `zowe.setup.vsam.storageClass` + If you use the `RLS` mode, a storage class is required. - `zowe.setup.vsam.volume` If you set to use the `NONRLS` mode, a storage volume is required. - To preview the member before submitting it, use the value `--security-dry-run`. Otherwise, the command automatically submits the JCL and waits for its completion. - ``` + ```plaintext >zwe init vsam -c ./zowe.yaml ------------------------------------------------------------------------------- >> Create VSAM storage for Zowe Caching Service @@ -104,33 +111,31 @@ To enable Personal Access Token support when using the Caching Service, **Infini > ``` -## redis +## Redis Redis is not available if you are running the API Mediation Layer on z/OS under Unix System Services. Usage of redis is intended for when API ML is running off platform, such as in a Linux or Windows container as part of a hybrid cloud deployment. - To enable this method, set the value of `zowe.components.caching-service.storage.mode` to `redis` in the `zowe.yaml` configuration file. There are a number of values to control the redis nodes, sentinel and ssl properties that need to be set in the `zowe.yaml` file. For more information on these properties and their values see [Redis configuration](../extend/extend-apiml/api-mediation-redis.md#redis-configuration). - - + To enable this method, set the value of `components.caching-service.storage.mode` to `redis` in the `zowe.yaml` configuration file. There are a number of values to control the redis nodes, sentinel and ssl properties that need to be set in the `zowe.yaml` file. For more information on these properties and their values see [Redis configuration](../extend/extend-apiml/api-mediation-redis.md#redis-configuration). + ```yaml - zowe: - components: - caching-service: - enabled: true - port: 7555 - storage: - size: 10000 - evictionStrategy: reject - mode: redis - redis: - masterNodeUri: - timeout: 60 - sentinel: - masterInstance - nodes - ssl: - enabled: true - keystore: - keystorePassword: - trustStore: - trustStorePassword + components: + caching-service: + enabled: true + port: 7555 + storage: + size: 10000 + evictionStrategy: reject + mode: redis + redis: + masterNodeUri: + timeout: 60 + sentinel: + masterInstance + nodes + ssl: + enabled: true + keystore: + keystorePassword: + trustStore: + trustStorePassword ``` From 8495cbfc3a210bde386e260cd9e3da68894fa7b6 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Tue, 19 Nov 2024 14:28:32 +0100 Subject: [PATCH 38/67] fix link Signed-off-by: Andrew Jandacek --- docs/user-guide/zos-components-installation-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/zos-components-installation-checklist.md b/docs/user-guide/zos-components-installation-checklist.md index ded54dccdb..bfdea575b1 100644 --- a/docs/user-guide/zos-components-installation-checklist.md +++ b/docs/user-guide/zos-components-installation-checklist.md @@ -82,7 +82,7 @@ You can configure your system to enable HA. This configuration is not required t | Verification Step | Task | Results | Time Estimate | |----|-----------|----|-------------| | [Verify Zowe Application Framework installation](../user-guide/verify-zowe-runtime-install.md#verifying-zowe-application-framework-installation) | Open the Zowe Desktop from a supported browser | You should be able to open the Zowe Desktop from a supported browser. | 20 minutes| -| [Verify API Mediation installation](../user-guide/verify-zowe-runtime-install.md#verifying-api-mediation-installation) |Use a REST API client to review the value of the status variable of the API Catalog service routed through the API Gateway | See the example presented in Verify API Mediation installation | 15 minutes | +| [Verify API Mediation installation](../user-guide/verify-zowe-runtime-install.md#verifying-api-mediation-layer-installation) |Use a REST API client to review the value of the status variable of the API Catalog service routed through the API Gateway | See the example presented in Verify API Mediation installation | 15 minutes | |[Verify z/OS Services installation](../user-guide/verify-zowe-runtime-install.md#verifying-zos-services-installation) |Zowe z/OS services usually are registered with Zowe APIML Discovery| You should see JSON format data of all jobs running on the system | 15 minutes | From c4cc96ab7dada66b77357113e79766e7fcbb6dbc Mon Sep 17 00:00:00 2001 From: anaxceron Date: Tue, 19 Nov 2024 10:44:01 -0600 Subject: [PATCH 39/67] clarification post docs-staging merge Signed-off-by: anaxceron --- release-handbook/major_release_workflow.md | 1 + 1 file changed, 1 insertion(+) diff --git a/release-handbook/major_release_workflow.md b/release-handbook/major_release_workflow.md index 802a58680b..5fb12d65ea 100644 --- a/release-handbook/major_release_workflow.md +++ b/release-handbook/major_release_workflow.md @@ -162,6 +162,7 @@ For major Zowe releases, follow the process outlined here. 10. Publish the staged doc to the live site: - Change the PR you opened in Step 6 to **Ready for review** mode to merge the new branch into the `docs-staging` branch. - All checks **must** pass before merging. If any checks fail, troubleshoot with Doc Squad members or developers well familiar with the `docs-site` repo to resolve. + - Any edits to the new major release doc now needs to be done in the `docs-staging` branch. - After the new branch is merged to `docs-staging`, create a PR to merge `docs-staging` into the `master` branch. - In your PR, do the following: - Add the Zowe release engineer to the reviewer list. From f5d2747958289894a5c28677688d89f51f27f546 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 20 Nov 2024 11:02:42 +0100 Subject: [PATCH 40/67] fix link Signed-off-by: Andrew Jandacek --- docs/user-guide/install-zowe-zos-convenience-build.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/install-zowe-zos-convenience-build.md b/docs/user-guide/install-zowe-zos-convenience-build.md index e45cb1d15d..562ea55277 100644 --- a/docs/user-guide/install-zowe-zos-convenience-build.md +++ b/docs/user-guide/install-zowe-zos-convenience-build.md @@ -1,10 +1,10 @@ # Installing the z/OS Build via Convenience Build (PAX file) -You install the Zowe™ convenience build by obtaining a PAX file and using this to create the Zowe runtime environment. +You can install the Zowe™ convenience build by obtaining a PAX file which is used to create the Zowe runtime environment. ## Introduction -The Zowe installation file for Zowe z/OS components is distributed as a PAX file that contains the runtimes and the scripts to install and launch the z/OS runtime. You must obtain the PAX file and transfer it to z/OS first. Then, to install, configure and start Zowe, you use the `zwe` command. This command defines help messages, logging options, and more. For details about how to use this command, see the [ZWE Server Command Reference](../appendix/zwe_server_command_reference/zwe/zwe.md). +The Zowe installation file for Zowe z/OS components is distributed as a PAX file that contains the runtimes and the scripts to install and launch the z/OS runtime. You must obtain the PAX file and transfer it to z/OS first. Then, to install, configure, and start Zowe, you use the `zwe` command. This command defines help messages, logging options, and more. For details about how to use this command, see the [ZWE Server Command Reference](../appendix/zwe_server_command_reference/zwe/zwe.md). The configuration data that is read by the `zwe` command are stored in a YAML configuration file named `zowe.yaml`. You modify the `zowe.yaml` file based on your environment. @@ -262,4 +262,4 @@ Copy components/zss/LOADLIB/ZWESAUX to IBMUSER.ZWEV2.SZWEAUTH ## Next steps -You successfully installed Zowe from the convenience build! However, before you start Zowe, you must complete several required configurations. The next step is to [Initialize the z/OS system and permissions](initialize-zos-system.md) for Zowe. +You successfully installed Zowe from the convenience build! However, before you start Zowe, you must complete several required configurations. The next step is [Initializing Zowe z/OS runtime](./configure-zowe-runtime.md). From 7c061b77ddf3694de985b4227e919a4e451eeb01 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 21 Nov 2024 10:45:48 +0100 Subject: [PATCH 41/67] remove duplication of COnfiguring address space naming from assign security permissions Signed-off-by: Andrew Jandacek --- .../assign-security-permissions-to-users.md | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/docs/user-guide/assign-security-permissions-to-users.md b/docs/user-guide/assign-security-permissions-to-users.md index a1f0db428e..700ede0f6c 100644 --- a/docs/user-guide/assign-security-permissions-to-users.md +++ b/docs/user-guide/assign-security-permissions-to-users.md @@ -58,25 +58,6 @@ see [zwe init security](../appendix/zwe_server_command_reference/zwe/init/zwe-in | ZSS | CSFSERV | `Multiple` | READ | Generate symmetric keys using ICSF that is used by [Zowe Desktop cookies](./configure-zos-system.md#configure-an-icsf-cryptographic-services-environment). | The list of IDs to enable include `CSF1TRD` , `CSF1TRC` , `CSF1SKE` , `CSF1SKD`. The full list of IDs is described in the z/OS Cryptographic Services user guide for your z/OS release level: [2.2](https://www.ibm.com/docs/en/zos/2.2.0?topic=ssl-racf-csfserv-resource-requirements), [2.3](https://www.ibm.com/docs/en/zos/2.3.0?topic=ssl-racf-csfserv-resource-requirements), [2.4](https://www.ibm.com/docs/en/zos/2.4.0?topic=ssl-racf-csfserv-resource-requirements) and [2.5](https://www.ibm.com/docs/en/zos/2.5.0?topic=ssl-racf-csfserv-resource-requirements). | | | | | | | Cross memory server (ZIS) | FACILITY | `ZWES.IS` | READ | Allow Zowe ZWESLSTC processes to access the Zowe ZIS cross memory server. | This parameter permits the Zowe main server to use ZIS cross memory server. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L329)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L560)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L780) | - -## Configuring address space job naming - -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. - -1. To display who is authorized to the profile, issue the following command: -``` -RLIST FACILITY BPX.JOBNAME AUTHUSER -``` - -2. Activate the facility class, permit `BPX.JOBNAME`, and refresh facility class: -``` -SETROPTS CLASSACT(FACILITY) RACLIST(FACILITY) -PERMIT BPX.JOBNAME CLASS(FACILITY) ID(ZWESVUSR) ACCESS(READ) -SETROPTS RACLIST(FACILITY) REFRESH -``` - -For more information, see [Setting up the UNIX-related FACILITY and SURROGAT class profiles](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.bpxb200/fclass.htm) in the "z/OS UNIX System Services" documentation. - ## Granting users permission to access z/OSMF Each TSO user ID that logs on to Zowe and uses Zowe services that use z/OSMF requires permission to access these z/OSMF services. It is necessary that every user ID be added to the group with the appropriate z/OSMF privileges, `IZUUSER` or `IZUADMIN` (default). From 81677bbfb951b3698c126a7747383837146269f7 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 21 Nov 2024 11:05:58 +0100 Subject: [PATCH 42/67] reformat init commands and remove items that are not applicable Signed-off-by: Andrew Jandacek --- docs/user-guide/zwe-init-subcommand-overview.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/zwe-init-subcommand-overview.md b/docs/user-guide/zwe-init-subcommand-overview.md index 9cf0faa2f8..075a006b77 100644 --- a/docs/user-guide/zwe-init-subcommand-overview.md +++ b/docs/user-guide/zwe-init-subcommand-overview.md @@ -7,13 +7,12 @@ Some of the following `zwe init` subcommands require elevated permissions. See t ::: - [Initializing Zowe custom data sets (`zwe init mvs`)](#initializing-zowe-custom-data-sets-zwe-init-mvs) -- [Procedure to initialize Zowe custom data sets](#procedure-to-initialize-zowe-custom-data-sets) + - [Procedure to initialize Zowe custom data sets](#procedure-to-initialize-zowe-custom-data-sets) - [Initializing Zowe security configurations (`zwe init security`)](#initializing-zowe-security-configurations-zwe-init-security) - [Performing APF authorization of load libraries (`zwe init apfauth`)](#performing-apf-authorization-of-load-libraries-zwe-init-apfauth) - [Configuring Zowe to use TLS certificates (`zwe init certificate`)](#configuring-zowe-to-use-tls-certificates-zwe-init-certificate) - [Installing Zowe main started tasks (`zwe init stc`)](#installing-zowe-main-started-tasks-zwe-init-stc) -- [(Deprecated) Creating VSAM caching service datasets (`zwe init vsam`)](#deprecated-creating-vsam-caching-service-datasets-zwe-init-vsam) -- [Next steps](#next-steps) + ## Initializing Zowe custom data sets (`zwe init mvs`) From 62b388cb882ba413d99b16282baba97c0bf66cf3 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 21 Nov 2024 11:32:20 +0100 Subject: [PATCH 43/67] fix link Signed-off-by: Andrew Jandacek --- docs/getting-started/zowe-high-availability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/zowe-high-availability.md b/docs/getting-started/zowe-high-availability.md index dbc37749d0..adac3adfab 100644 --- a/docs/getting-started/zowe-high-availability.md +++ b/docs/getting-started/zowe-high-availability.md @@ -30,7 +30,7 @@ If you are running the Caching Service on z/OS, there are three storage methods - Part of the Caching service - Does not need separate processes - Highly performant -- [VSAM (*deprecated*)](../user-guide/configure-caching-service-ha.md#vsam) +- [VSAM (*deprecated*)](../user-guide/configure-caching-service-ha.md#vsam-deprecated) - Familiar to z/OS engineers - Slow - [Redis](../extend/extend-apiml/api-mediation-redis.md#redis-configuration) From 2342ac8abf267f537fbb78ef99f3d1aa5c0ad50a Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 21 Nov 2024 14:09:48 +0100 Subject: [PATCH 44/67] remove initialize-security-configuration.md. COntent has been moved to parent topic configuring-security Signed-off-by: Andrew Jandacek --- sidebars.js | 1 - 1 file changed, 1 deletion(-) diff --git a/sidebars.js b/sidebars.js index aaad3e4a69..b11c847785 100644 --- a/sidebars.js +++ b/sidebars.js @@ -207,7 +207,6 @@ module.exports = { label: "Configuring security", link: { type: "doc", id: "user-guide/configuring-security" }, items: [ - "user-guide/initialize-security-configuration", "user-guide/apf-authorize-load-library", "user-guide/configure-zos-system", "user-guide/assign-security-permissions-to-users", From aa024d509bff91b32b1407aee5ef4c456d339b20 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 21 Nov 2024 16:20:34 +0100 Subject: [PATCH 45/67] fix link to initializing security config Signed-off-by: Andrew Jandacek --- docs/user-guide/zos-components-installation-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/zos-components-installation-checklist.md b/docs/user-guide/zos-components-installation-checklist.md index bfdea575b1..4422b18bdf 100644 --- a/docs/user-guide/zos-components-installation-checklist.md +++ b/docs/user-guide/zos-components-installation-checklist.md @@ -33,7 +33,7 @@ Configure Zowe and your z/OS system to run Zowe with z/OS. | Task | Results | Time Estimate | |--------------------|----|------| |[Review Configuring security](./configuring-security.md) | Knowledge about which tasks need to be performed by the security administrator. | 10 minutes| -[Initialize Zowe security configurations](./initialize-security-configuration) | The JCL member to configure the z/OS system is created. | 10 minutes | +[Initialize Zowe security configurations](./configuring-security.md#initialize-zowe-security-configurations) | The JCL member to configure the z/OS system is created. | 10 minutes | [Perform APF authorization of load libraries](./apf-authorize-load-library.md) | APF authorization is granted to load libraries. | 10 minutes | [Address z/OS requirements for Zowe](./configure-zos-system.md) | Your z/OS and security product are configured. | 2 hours | [Assign security permissions to users](./assign-security-permissions-to-users.md) | Zowe user is created and is assigned all required permissions. | 30 minutes | From 9b92e85046797928cada94324bf789fefcc73bf9 Mon Sep 17 00:00:00 2001 From: Zowe Robot Date: Fri, 22 Nov 2024 00:32:36 +0000 Subject: [PATCH 46/67] Update error codes Signed-off-by: Zowe Robot --- docs/troubleshoot/troubleshoot-apiml-error-codes.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/troubleshoot/troubleshoot-apiml-error-codes.md b/docs/troubleshoot/troubleshoot-apiml-error-codes.md index c69a4f0e86..ee2bc6ef5d 100644 --- a/docs/troubleshoot/troubleshoot-apiml-error-codes.md +++ b/docs/troubleshoot/troubleshoot-apiml-error-codes.md @@ -1339,6 +1339,18 @@ The following error message codes may appear on logs or API responses. Use the f Make sure that the external Gateway service is running and the truststore of the both Gateways contain the corresponding certificate. +### ZWESG101E + + An internal exception occurred in ZAAS service %s. + + **Reason:** + + ZAAS cannot process authentication required to finish the request. + + **Action:** + + Make sure that the ZAAS is configured well and check all security requirements. + ### ZWESG429E Request was denied access. From 295b3a5e9d0ed064606b1b982e9a6dec3df3a1fb Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Fri, 22 Nov 2024 14:57:17 +0100 Subject: [PATCH 47/67] fix links and title in checklist Signed-off-by: Andrew Jandacek --- docs/user-guide/zos-components-installation-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/zos-components-installation-checklist.md b/docs/user-guide/zos-components-installation-checklist.md index 4422b18bdf..20168128f7 100644 --- a/docs/user-guide/zos-components-installation-checklist.md +++ b/docs/user-guide/zos-components-installation-checklist.md @@ -35,7 +35,7 @@ Configure Zowe and your z/OS system to run Zowe with z/OS. |[Review Configuring security](./configuring-security.md) | Knowledge about which tasks need to be performed by the security administrator. | 10 minutes| [Initialize Zowe security configurations](./configuring-security.md#initialize-zowe-security-configurations) | The JCL member to configure the z/OS system is created. | 10 minutes | [Perform APF authorization of load libraries](./apf-authorize-load-library.md) | APF authorization is granted to load libraries. | 10 minutes | -[Address z/OS requirements for Zowe](./configure-zos-system.md) | Your z/OS and security product are configured. | 2 hours | +[Customize z/OS system security](./configure-zos-system.md) | Your z/OS and security product are configured. | 2 hours | [Assign security permissions to users](./assign-security-permissions-to-users.md) | Zowe user is created and is assigned all required permissions. | 30 minutes | From 0d38ae64257fc62c480496803ecce1fd7cf2908d Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 21 Nov 2024 14:09:48 +0100 Subject: [PATCH 48/67] remove initialize-security-configuration.md. COntent has been moved to parent topic configuring-security Signed-off-by: Andrew Jandacek From ac47dee901cfd22ec7372fe03c8ae5f46a45c888 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Fri, 22 Nov 2024 17:02:57 +0100 Subject: [PATCH 49/67] apply security doc reorg to v2.18 Signed-off-by: Andrew Jandacek --- .../user-guide/apf-authorize-load-library.md | 6 +- .../user-guide/configure-zos-system.md | 947 +++++++++++------- .../user-guide/configure-zowe-runtime.md | 8 +- .../user-guide/configuring-overview.md | 4 +- .../user-guide/configuring-security.md | 101 +- .../user-guide/initialize-zos-system.md | 2 +- .../user-guide/systemrequirements-zos.md | 4 + .../user-guide/verify-zowe-runtime-install.md | 39 +- .../zos-components-installation-checklist.md | 4 +- .../zwe-init-subcommand-overview.md | 74 +- .../version-v2.18.x-sidebars.json | 1 - 11 files changed, 772 insertions(+), 418 deletions(-) diff --git a/versioned_docs/version-v2.18.x/user-guide/apf-authorize-load-library.md b/versioned_docs/version-v2.18.x/user-guide/apf-authorize-load-library.md index f95c51b891..317be16aaf 100644 --- a/versioned_docs/version-v2.18.x/user-guide/apf-authorize-load-library.md +++ b/versioned_docs/version-v2.18.x/user-guide/apf-authorize-load-library.md @@ -27,10 +27,8 @@ APF authorize IBMUSER.ZWEV2.CUST.ZWESAPL #> ``` :::note -If you do not have permissions to update your security configurations, use `security-dry-run`. We recommend you inform your security administrator to review your job content. -::: - -Specify `--security-dry-run` to have the command echo the commands that need to be run without executing the command. +If you do not have permissions to update your security configurations, append the flag `--security-dry-run` to have the command echo the commands that need to be run without executing the command. We recommend you inform your security administrator to review your job content. +::: ``` SETPROG APF,ADD,DSNAME=IBMUSER.ZWEV2.SZWEAUTH,SMS diff --git a/versioned_docs/version-v2.18.x/user-guide/configure-zos-system.md b/versioned_docs/version-v2.18.x/user-guide/configure-zos-system.md index 9709b347b7..c08ef3f344 100644 --- a/versioned_docs/version-v2.18.x/user-guide/configure-zos-system.md +++ b/versioned_docs/version-v2.18.x/user-guide/configure-zos-system.md @@ -1,51 +1,55 @@ -# Addressing z/OS requirements for Zowe +# Customizing z/OS system security -As a security administrator it is necessary to configure the z/OS system for Zowe. Review the following article to learn about z/OS prerequisites, and z/OS configuration requirements for specific settings. +As a security administrator, configure your z/OS system according to the specific features and functionalities you choose to include in your Zowe installation. Review the following article for specific configuration steps that apply to these features and fuctionalities. :::info Required role: security administrator ::: -## z/OS prerequisites -Be sure your z/OS system meets the following prerequisites: - -- z/OS version is in active support, such as Version 2.3, Version 2.4, Version 2.5 and Version 3.1 +:::note +Before performing configuration steps specific to your use case, ensure that you meet the z/OS system requirements presented in the section _Preparing for installation_. For detailed information, see [Addressing z/OS requirements](./systemrequirements-zos.md). +::: + + Review the following table to determine which configuration steps are required based on your Zowe use case. + +| Purpose | Applicable Zowe Component(s) | Configuration step | +| --- | --- | --- | +| Set the names for the different z/OS UNIX address spaces for the Zowe runtime components.
**Important:** This configuration step is required. | All components | [Configure address space job naming](#configure-address-space-job-naming) | +| To use Zowe desktop. This step generates random numbers for zssServer that the Zowe desktop uses. | Application Framework | [Configure an ICSF cryptographic services environment](#configure-an-icsf-cryptographic-services-environment) | +| To allow users to log on to the Zowe desktop through impersonation. | Application Framework | [Configure security environment switching](#configure-security-environment-switching) | +| Required for TSS only. A TSS FACILITY needs to be defined and assigned to the `ZWESLSTC` started task. | All components | [Configure multi-user address space for TSS only](#configure-multi-user-address-space-for-tss-only) | +| Required to manually create the user ID and groups in your z/OS environment. Tasks are performed as part of [Zowe runtime configuration](./configure-zowe-runtime.md) | All components | [Configure user IDs and groups for the Zowe started tasks](#configure-user-ids-and-groups-for-the-zowe-started-tasks) | +| Required to configure the started task ZWESLSTC to run under the correct user ID and group. Tasks are performed as part of [Zowe runtime configuration](./configure-zowe-runtime.md).| All components | [Configure ZWESLSTC to run Zowe high availability instances under ZWESVUSR user ID](#configure-zweslstc-to-run-zowe-high-availability-instances-under-zwesvusr-user-id). | +| Required to configure the cross memory server for SAF to guard against access by non-privileged clients. Tasks are performed as part of [Zowe runtime configuration](./configure-zowe-runtime.md).| Application Framework | [Configure the cross memory server for SAF](#configure-the-cross-memory-server-for-saf) | +| Required for API Mediation Layer to map a client certificate to a z/OS identity. | API ML | [Configure main Zowe server to use client certificate identity mapping](#configure-main-zowe-server-to-use-client-certificate-identity-mapping) | +| Required for API ML to map the association between a z/OS user ID and a distributed user identity. | API ML | [Configure main Zowe server to use distributed identity mapping](#configure-main-zowe-server-to-use-distributed-identity-mapping) | +| To configure SAF Identity tokens on z/OS so that they can be used by Zowe components like zss or API Mediation Layer. | Application Framework
API ML | [Configure signed SAF Identity tokens IDT](#configure-signed-saf-identity-tokens-idt) | +| Required for API Mediation Layer to issue SMF records. | API ML | [Configure the main Zowe server to issue SMF records](api-mediation/api-mediation-smf.md#configure-the-main-zowe-server-to-issue-smf-records) | +| To use multi-factor authentication (MFA) | All components | [Multi-Factor Authentication (MFA)](#multi-factor-authentication-mfa) | +| To use Single Sign-On (SSO) | All components | [Single Sign-On (SSO)](#single-sign-on-sso) | +| To use OIDC Authentication with API Mediation Layer | API ML | [API Mediation Layer OIDC Authentication](#api-mediation-layer-oidc-authentication) | - :::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). - ::: +### Configure address space job naming -- zFS volume has at least 833 mb of free space for Zowe server components, their keystore, instance configuration files and logs, and third-party plug-ins. +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. -- (Optional, recommended) z/OS OpenSSH V2.2.0 or later - - Some features of Zowe require SSH, such as the Desktop's SSH terminal. Install and manage Zowe via SSH, as an alternative to OMVS over TN3270. +:::note +This procedure may require security administrator authorization. Consult with your security administrator. +::: -- (Optional, recommended) Parallel Sysplex. - - To deploy Zowe for high availability, a Parallel Sysplex environment is recommended. For more information, see [Configuring Sysplex for high availability](configure-sysplex.md). +To display who is authorized to the profile, issue the following command: +``` +RLIST FACILITY BPX.JOBNAME AUTHUSER +``` - ## Settings specific configuration requirements - -Configuration of your z/OS system is dependent on the specific Zowe features and functionalities you would like to employ with your Zowe installation. Review the following table to determine which configuration steps are required based on your Zowe use case. - -| Purpose | Configuration step | -| --- | --- | -| Set the names for the different z/OS UNIX address spaces for the Zowe runtime components.
**Important:** This configuration step is required. | [Configure address space job naming](#configure-address-space-job-naming) | -| To use Zowe desktop. This step generates random numbers for zssServer that the Zowe desktop uses. | [Configure an ICSF cryptographic services environment](#configure-an-icsf-cryptographic-services-environment) | -| To allow users to log on to the Zowe desktop through impersonation. | [Configure security environment switching](#configure-security-environment-switching) | -| Required for TSS only. A TSS FACILITY needs to be defined and assigned to the `ZWESLSTC` started task. | [Configure multi-user address space for TSS only](#configure-multi-user-address-space-for-tss-only) | -| Required if you have not run `ZWESECUR` and are manually creating the user ID and groups in your z/OS environment. | [Configure user IDs and groups for the Zowe started tasks](#configure-user-ids-and-groups-for-the-zowe-started-tasks) | -| Required if you have not run `ZWESECUR` and are configuring your z/OS environment manually. This step describes how to configure the started task ZWESLSTC to run under the correct user ID and group. | [Configure ZWESLSTC to run Zowe high availability instances under ZWESVUSR user ID](#configure-zweslstc-to-run-zowe-high-availability-instances-under-zwesvusr-user-id) | -| Required if you have not run `ZWESECUR` and are configuring your z/OS environment manually. This step describes how to configure the cross memory server for SAF to guard against access by non-privileged clients. | [Configure the cross memory server for SAF](#configure-the-cross-memory-server-for-saf) | -| Required for API Mediation Layer to map a client certificate to a z/OS identity. | [Configure main Zowe server to use client certificate identity mapping](#configure-main-zowe-server-to-use-client-certificate-identity-mapping) | -| Required for API ML to map the association between a z/OS user ID and a distributed user identity. | [Configure main Zowe server to use distributed identity mapping](#configure-main-zowe-server-to-use-distributed-identity-mapping) | -| To configure SAF Identity tokens on z/OS so that they can be used by Zowe components like zss or API Mediation Layer. | [Configure signed SAF Identity tokens IDT](#configure-signed-saf-identity-tokens-idt) | -| Required for API Mediation Layer to issue SMF records. | [Configure the main Zowe server to issue SMF records](api-mediation/api-mediation-smf.md#configure-the-main-zowe-server-to-issue-smf-records) | -| To use multi-factor authentication (MFA) | [Multi-Factor Authentication (MFA)](#multi-factor-authentication-mfa) | -| To use Single Sign-On (SSO) | [Single Sign-On (SSO)](#single-sign-on-sso) | -| To use OIDC Authentication with API Mediation Layer | [API Mediation Layer OIDC Authentication](#api-mediation-layer-oidc-authentication) | +Additionally, you need to activate facility class, permit `BPX.JOBNAME`, and refresh facility class: +``` +SETROPTS CLASSACT(FACILITY) RACLIST(FACILITY) +PERMIT BPX.JOBNAME CLASS(FACILITY) ID(ZWESVUSR) ACCESS(READ) +SETROPTS RACLIST(FACILITY) REFRESH +``` +For more information, see [Setting up the UNIX-related FACILITY and SURROGAT class profiles](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.bpxb200/fclass.htm) in the "z/OS UNIX System Services" documentation. ### Configure an ICSF cryptographic services environment @@ -66,62 +70,78 @@ Define or check the following configurations depending on whether ICSF is alread - Create CKDS, PKDS, TKDS VSAM data sets. - Define and activate the CSFSERV class: - - If you use RACF, issue the following commands: - ``` - RDEFINE CSFSERV profile-name UACC(NONE) - ``` - ``` - PERMIT profile-name CLASS(CSFSERV) ID(tcpip-stackname) ACCESS(READ) - ``` - ``` - PERMIT profile-name CLASS(CSFSERV) ID(userid-list) ... [for - userids IKED, NSSD, and Policy Agent] - ``` - ``` - SETROPTS CLASSACT(CSFSERV) - ``` - ``` - SETROPTS RACLIST(CSFSERV) REFRESH - ``` - - If you use ACF2, issue the following commands (note that `profile-prefix` and `profile-suffix` are user-defined): - ``` - SET CONTROL(GSO) - ``` - ``` - INSERT CLASMAP.CSFSERV RESOURCE(CSFSERV) RSRCTYPE(CSF) - ``` - ``` - F ACF2,REFRESH(CLASMAP) - ``` - ``` - SET RESOURCE(CSF) - ``` - ``` - RECKEY profile-prefix ADD(profile-suffix uid(UID string for tcpip-stackname) SERVICE(READ) ALLOW) - ``` - ``` - RECKEY profile-prefix ADD(profile-suffix uid(UID string for IZUSVR) SERVICE(READ) ALLOW) - ``` - (repeat for userids IKED, NSSD, and Policy Agent) +
+Click here for command details for RACF. - ``` - F ACF2,REBUILD(CSF) - ``` - - If you use Top Secret, issue the following command (note that `profile-prefix` and `profile-suffix` are user defined): - ``` - TSS ADDTO(owner-acid) RESCLASS(CSFSERV) - ``` - ``` - TSS ADD(owner-acid) CSFSERV(profile-prefix.) - ``` - ``` - TSS PERMIT(tcpip-stackname) CSFSERV(profile-prefix.profile-suffix) ACCESS(READ) - ``` - ``` - TSS PERMIT(user-acid) CSFSERV(profile-prefix.profile-suffix) ACCESS(READ) - ``` - (repeat for user-acids IKED, NSSD, and Policy Agent) +If you use RACF, issue the following commands: +``` +RDEFINE CSFSERV profile-name UACC(NONE) +``` +``` +PERMIT profile-name CLASS(CSFSERV) ID(tcpip-stackname) ACCESS(READ) +``` +``` +PERMIT profile-name CLASS(CSFSERV) ID(userid-list) ... [for +userids IKED, NSSD, and Policy Agent] +``` +``` +SETROPTS CLASSACT(CSFSERV) +``` +``` +SETROPTS RACLIST(CSFSERV) REFRESH +``` + +
+ +
+Click here for command details for ACF2. + +If you use ACF2, issue the following commands (note that `profile-prefix` and `profile-suffix` are user-defined): +``` +SET CONTROL(GSO) +``` +``` +INSERT CLASMAP.CSFSERV RESOURCE(CSFSERV) RSRCTYPE(CSF) +``` +``` +F ACF2,REFRESH(CLASMAP) +``` +``` +SET RESOURCE(CSF) +``` +``` +RECKEY profile-prefix ADD(profile-suffix uid(UID string for tcpip-stackname) SERVICE(READ) ALLOW) +``` +``` +RECKEY profile-prefix ADD(profile-suffix uid(UID string for IZUSVR) SERVICE(READ) ALLOW) +``` +(repeat for userids IKED, NSSD, and Policy Agent) + +``` +F ACF2,REBUILD(CSF) +``` + +
+ +
+Click here for command details for Top Secret + +If you use Top Secret, issue the following command (note that `profile-prefix` and `profile-suffix` are user defined): +``` +TSS ADDTO(owner-acid) RESCLASS(CSFSERV) +``` +``` +TSS ADD(owner-acid) CSFSERV(profile-prefix.) +``` +``` +TSS PERMIT(tcpip-stackname) CSFSERV(profile-prefix.profile-suffix) ACCESS(READ) +``` +``` +TSS PERMIT(user-acid) CSFSERV(profile-prefix.profile-suffix) ACCESS(READ) +``` +(repeat for user-acids IKED, NSSD, and Policy Agent) +
:::note Notes - Determine whether you want SAF authorization checks against `CSFSERV` and set `CSF.CSFSERV.AUTH.CSFRNG.DISABLE` accordingly. @@ -138,153 +158,210 @@ To enable impersonation, you must grant the user ID `ZWESVUSR` associated with t 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: - ``` - RLIST FACILITY BPX.SERVER AUTHUSER - ``` - ``` - RLIST FACILITY BPX.DAEMON AUTHUSER - ``` -- If you use Top Secret, issue the following commands: - ``` - TSS WHOHAS IBMFAC(BPX.SERVER) - ``` - ``` - TSS WHOHAS IBMFAC(BPX.DAEMON) - ``` -- If you use ACF2, issue the following commands: - ``` - SET RESOURCE(FAC) - ``` - ``` - LIST BPX - ``` +
+Click here for command details for RACF. + +If you use RACF, issue the following commands: +``` +RLIST FACILITY BPX.SERVER AUTHUSER +``` +``` +RLIST FACILITY BPX.DAEMON AUTHUSER +``` + +
+ +
+Click here for command details for Top Secret. + +If you use Top Secret, issue the following commands: +``` +TSS WHOHAS IBMFAC(BPX.SERVER) +``` +``` +TSS WHOHAS IBMFAC(BPX.DAEMON) +``` + +
+ +
+Click here for command details for ACF2. + +If you use ACF2, issue the following commands: +``` +SET RESOURCE(FAC) +``` +``` +LIST BPX +``` + +
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: +
+Click here for procedure details for RACF. + +If you use RACF, complete the following steps: - 1. Activate and RACLIST the FACILITY class. This may have already been done on the z/OS environment if another z/OS server has been previously configured to take advantage of the ability to change its security environment, such as the FTPD daemon that is included with z/OS Communications Server TCP/IP services. - ``` - SETROPTS GENERIC(FACILITY) - SETROPTS CLASSACT(FACILITY) RACLIST(FACILITY) - ``` - 2. Define the impersonation profiles. This may have already been done on behalf of another server such as the FTPD daemon. - ``` - RDEFINE FACILITY BPX.SERVER UACC(NONE) - ``` - ``` - RDEFINE FACILITY BPX.DAEMON UACC(NONE) - ``` - 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.DAEMON CLASS(FACILITY) ID() ACCESS(UPDATE) - ``` - where `` is `ZWESVUSR` unless a different user ID is being used for the z/OS environment. - - /* Activate these changes */ - - ``` - SETROPTS RACLIST(FACILITY) REFRESH - ``` - 4. Issue the following commands to check whether permission has been successfully granted: - ``` - RLIST FACILITY BPX.SERVER AUTHUSER - ``` - ``` - RLIST FACILITY BPX.DAEMON AUTHUSER - ``` -- If you use Top Secret, complete the following steps: +1. Activate and RACLIST the FACILITY class. This may have already been done on the z/OS environment if another z/OS server has been previously configured to take advantage of the ability to change its security environment, such as the FTPD daemon that is included with z/OS Communications Server TCP/IP services. + +``` +SETROPTS GENERIC(FACILITY) +SETROPTS CLASSACT(FACILITY) RACLIST(FACILITY) +``` +2. Define the impersonation profiles. This may have already been done on behalf of another server such as the FTPD daemon. +``` +RDEFINE FACILITY BPX.SERVER UACC(NONE) +``` +``` +RDEFINE FACILITY BPX.DAEMON UACC(NONE) +``` +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.DAEMON CLASS(FACILITY) ID() ACCESS(UPDATE) +``` +where: + +* `` is `ZWESVUSR` unless a different user ID is being used for the z/OS environment. + +/* Activate these changes */ + +``` +SETROPTS RACLIST(FACILITY) REFRESH +``` +4. Issue the following commands to check whether permission has been successfully granted: + +``` +RLIST FACILITY BPX.SERVER AUTHUSER +``` +``` +RLIST FACILITY BPX.DAEMON AUTHUSER +``` + +
+ +
+Click here for procedure details for Top Secret. + +If you use Top Secret, complete the following steps: - 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.DAEMON) ACCESS(UPDATE) - ``` - 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) - ``` - ``` - TSS WHOHAS IBMFAC(BPX.DAEMON) - ``` -- If you use ACF2, complete the following steps: - 1. Define the BPX Resource and access for ``. - ``` - SET RESOURCE(FAC) - ``` - ``` - RECKEY BPX ADD(SERVER 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. - ``` - F ACF2,REBUILD(FAC) - ``` - 2. Issue the following commands and review the output to check whether permission has been successfully granted: - ``` - SET RESOURCE(FAC) - ``` - ``` - LIST BPX - ``` +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.DAEMON) ACCESS(UPDATE) +``` +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) +``` +``` +TSS WHOHAS IBMFAC(BPX.DAEMON) +``` + +
+ +
+Click here for procedure details for ACF2. + +If you use ACF2, complete the following steps: + +1. Define the BPX Resource and access for ``. +``` +SET RESOURCE(FAC) +``` +``` +RECKEY BPX ADD(SERVER 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. +``` +F ACF2,REBUILD(FAC) +``` + +2. Issue the following commands and review the output to check whether permission has been successfully granted: +``` +SET RESOURCE(FAC) +``` +``` +LIST BPX +``` + +
+ You must also grant READ access to the OMVSAPPL profile in the APPL class to the Zowe STC user as well as **all other Zowe users** using various Zowe features. Skip the following steps when the OMVSAPPL profile is not defined in your environment. -- If you use RACF, complete the following steps: +
+Click here for procedure details for RACF. - 1. Check if you already have the required access defined as part of the environment configuration. Skip the following steps if access is already granted. - ``` - RLIST APPL OMVSAPPL AUTHUSER - ``` +If you use RACF, complete the following steps: - 2. Issue the following commands and review the output to check if permission has been successfully granted: - ``` - PERMIT OMVSAPPL CLASS(APPL) ID() ACCESS(READ) - SETROPTS RACLIST(APPL) REFRESH - ``` +1. Check if you already have the required access defined as part of the environment configuration. Skip the following steps if access is already granted. +``` +RLIST APPL OMVSAPPL AUTHUSER +``` -- If you use Top Secret, complete the following steps: +2. Issue the following commands and review the output to check if permission has been successfully granted: +``` +PERMIT OMVSAPPL CLASS(APPL) ID() ACCESS(READ) +SETROPTS RACLIST(APPL) REFRESH +``` - 1. Check if you already have the required access as part of the environment configuration. Skip the following steps if access is already granted. - ``` - TSS WHOHAS APPL(OMVSAPPL) - ``` +
- 2. Issue the following commands and review the output to check if permission has been successfully granted: - ``` - TSS PERMIT() APPL(OMVSAPPL) - ``` +
+Click here for procedure details for Top Secret. -- If you use ACF2, complete the following steps: +If you use Top Secret, complete the following steps: - 1. Check if you already have the required access defined as part of the environment configuration. Skip the following steps if access is already granted. - ``` - SET RESOURCE(APL) - LIST OMVSAAPL - ``` +1. Check if you already have the required access as part of the environment configuration. Skip the following steps if access is already granted. +``` +TSS WHOHAS APPL(OMVSAPPL) +``` - 2. Issue the following commands and review the output to check if permission has been successfully granted: - ``` - SET RESOURCE(APL) - RECKEY OMVSAPPL ADD(SERVICE(READ) ROLE() ALLOW) - F ACF2,REBUILD(APL) - ``` +2. Issue the following commands and review the output to check if permission has been successfully granted: +``` +TSS PERMIT() APPL(OMVSAPPL) +``` + +
+ +
+Click here for procedure details for ACF2. + +If you use ACF2, complete the following steps: + +1. Check if you already have the required access defined as part of the environment configuration. Skip the following steps if access is already granted. +``` +SET RESOURCE(APL) +LIST OMVSAAPL +``` + +2. Issue the following commands and review the output to check if permission has been successfully granted: +``` +SET RESOURCE(APL) +RECKEY OMVSAPPL ADD(SERVICE(READ) ROLE() ALLOW) +F ACF2,REBUILD(APL) +``` + +
### Configure address space job naming -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. +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. :::note This procedure may require security administrator authorization. Consult with your security administrator. @@ -352,82 +429,132 @@ If you have run `ZWESECUR`, you do not need to perform the steps described in th If you have not run `ZWESECUR` and are manually creating the user ID and groups in your z/OS environment, the commands are described below for reference. -- To create the `ZWEADMIN` group, issue the following command: +- To create the `ZWEADMIN` group, issue the following command according to your ESM: - **RACF:** - ``` - ADDGROUP ZWEADMIN OMVS(AUTOGID) - - DATA('STARTED TASK GROUP WITH OMVS SEGEMENT') - ``` - **TSS:** +
+ Click here for command details for RACF. + + **RACF:** + ``` + ADDGROUP ZWEADMIN OMVS(AUTOGID) - + DATA('STARTED TASK GROUP WITH OMVS SEGEMENT') + ``` +
+ +
+ Click here for command details for Top Secret. + + **TSS:** ``` TSS CREATE() TYPE(GROUP) + NAME('ZOWE ADMINISTRATORS') + DEPT() TSS ADD() GID() ``` - **ACF2:** + +
+ +
+ Click here for command details for ACF2. + + **ACF2:** ``` SET PROFILE(GROUP) DIV(OMVS) INSERT AUTOGID F ACF2,REBUILD(GRP),CLASS(P) + ``` -- To create the `ZWESVUSR` user ID for the main Zowe started task, issue the following command: +
- **RACF:** - ``` - ADDUSER - - NOPASSWORD - - DFLTGRP() - - OMVS(HOME(/tmp) PROGRAM(/bin/sh) AUTOUID) - - NAME('ZOWE SERVER') - - DATA('ZOWE MAIN SERVER') - ``` - **TSS:** - ``` - TSS CREATE() TYPE(USER) PROTECTED + - NAME('ZOWE MAIN SERVER') + - DEPT() - TSS ADD() GROUP() + - DFLTGRP() + - HOME(/tmp) OMVSPGM(/bin/sh) UID() - ``` - **ACF2:** - ``` - SET LID - INSERT STC GROUP() - SET PROFILE(USER) DIV(OMVS) - INSERT AUTOUID HOME(/tmp) OMVSPGM(/bin/sh) - F ACF2,REBUILD(USR),CLASS(P),DIVISION(OMVS) - ``` - -- To create the `ZWESIUSR` group for the Zowe cross memory server started task, issue the following command: - **RACF:** - ``` - ADDUSER - - NOPASSWORD - - DFLTGRP() - - OMVS(HOME(/tmp) PROGRAM(/bin/sh) AUTOUID) - - NAME('ZOWE XMEM SERVER') - - DATA('ZOWE XMEM CROSS MEMORY SERVER') - ``` - **TSS:** - ``` - TSS CREATE() TYPE(USER) PROTECTED + + * To create the `ZWESVUSR` user ID for the main Zowe started task, issue the following command according to your ESM: + +
+ + Click here for command details for RACF. + + **RACF:** + ``` + ADDUSER - + NOPASSWORD - + DFLTGRP() - + OMVS(HOME(/tmp) PROGRAM(/bin/sh) AUTOUID) - + NAME('ZOWE SERVER') - + DATA('ZOWE MAIN SERVER') + ``` +
+ +
+ Click here for command details for Top Secret. + + **TSS:** + ``` + TSS CREATE() TYPE(USER) PROTECTED + + NAME('ZOWE MAIN SERVER') + + DEPT() + TSS ADD() GROUP() + + DFLTGRP() + + HOME(/tmp) OMVSPGM(/bin/sh) UID() + ``` + +
+ +
+ Click here for command details for ACF2. + + **ACF2:** + ``` + SET LID + INSERT STC GROUP() + SET PROFILE(USER) DIV(OMVS) + INSERT AUTOUID HOME(/tmp) OMVSPGM(/bin/sh) + F ACF2,REBUILD(USR),CLASS(P),DIVISION(OMVS) + ``` +
+ +- To create the `ZWESIUSR` group for the Zowe cross memory server started task, issue the following command according to your ESM: + +
+ Click here for command details for RACF. + + **RACF:** + ``` + ADDUSER - + NOPASSWORD - + DFLTGRP() - + OMVS(HOME(/tmp) PROGRAM(/bin/sh) AUTOUID) - + NAME('ZOWE XMEM SERVER') - + DATA('ZOWE XMEM CROSS MEMORY SERVER') + ``` + +
+ +
+ Click here for command details for Top Secret. + + **TSS:** + ``` + TSS CREATE() TYPE(USER) PROTECTED + NAME('ZOWE ZIS CROSS MEMORY SERVER') + DEPT() - TSS ADD() GROUP() + + TSS ADD() GROUP() + DFLTGRP() + HOME(/tmp) OMVSPGM(/bin/sh) UID(&ZISUID.) - ``` - **ACF2:** - ``` - SET LID - INSERT STC GROUP() - SET PROFILE(USER) DIV(OMVS) - INSERT AUTOUID HOME(/tmp) OMVSPGM(/bin/sh) - F ACF2,REBUILD(USR),CLASS(P),DIVISION(OMVS) - ``` + ``` +
+ +
+ Click here for command details for ACF2. + + **ACF2:** + ``` + SET LID + INSERT STC GROUP() + SET PROFILE(USER) DIV(OMVS) + INSERT AUTOUID HOME(/tmp) OMVSPGM(/bin/sh) + F ACF2,REBUILD(USR),CLASS(P),DIVISION(OMVS) + ``` + +
### Configure ZWESLSTC to run Zowe high availability instances under ZWESVUSR user ID @@ -439,27 +566,41 @@ If you have run `ZWESECUR`, you do not need to perform the steps described in th ... ``` -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 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. Issue the following commands according to your ESM: -- 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) - ``` +
+Click here for command details for RACF. -- If you use ACF2, issue the following commands: +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) +``` +
+ +
+Click here for command details for ACF2. + +If you use ACF2, issue the following commands: - ``` - SET CONTROL(GSO) - INSERT STC.ZWESLSTC LOGONID(ZWESVUSR) GROUP(ZWEADMIN) STCID(ZWESLSTC) - F ACF2,REFRESH(STC) - ``` +``` +SET CONTROL(GSO) +INSERT STC.ZWESLSTC LOGONID(ZWESVUSR) GROUP(ZWEADMIN) STCID(ZWESLSTC) +F ACF2,REFRESH(STC) +``` -- If you use Top Secret, issue the following commands: +
+ +
+Click here for command details for Top Secret. + +If you use Top Secret, issue the following commands: + +``` +TSS ADDTO(STC) PROCNAME(ZWESLSTC) ACID(ZWESVUSR) +``` - ``` - TSS ADDTO(STC) PROCNAME(ZWESLSTC) ACID(ZWESVUSR) - ``` +
### Configure the cross memory server for SAF @@ -474,11 +615,14 @@ 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 main Zowe started task 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 Zowe server under the `ZWESVUSR` user. +To perform these steps, 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. + +
+Click here for command details for RACF. -- If you use RACF, issue the following commands: +If you use RACF, issue the following commands: - To see the current class settings, use: ``` @@ -510,7 +654,12 @@ To do this, issue the following commands that are also included in the `ZWESECUR ``` This shows the user IDs who have access to the `ZWES.IS` class, which should include Zowe's started task user ID with READ access. -- If you use ACF2, issue the following commands: +
+ +
+Click here for command details for ACF2. + +If you use ACF2, issue the following commands: ``` SET RESOURCE(FAC) @@ -522,7 +671,12 @@ To do this, issue the following commands that are also included in the `ZWESECUR F ACF2,REBUILD(FAC) ``` -- If you use Top Secret, issue the following commands, where `owner-acid` can be IZUSVR or a different ACID: +
+ +
+Click here for command details for Top Secret. + +If you use Top Secret, issue the following commands, where `owner-acid` can be IZUSVR or a different ACID: ``` TSS ADD(`owner-acid`) IBMFAC(ZWES.) @@ -530,6 +684,7 @@ To do this, issue the following commands that are also included in the `ZWESECUR ``` TSS PERMIT(ZWESVUSR) IBMFAC(ZWES.IS) ACCESS(READ) ``` +
:::note Notes - The cross memory server treats "no decision" style SAF return codes as failures. If there is no covering profile for the `ZWES.IS` resource in the FACILITY class, the request will be denied. @@ -538,21 +693,22 @@ To do this, issue the following commands that are also included in the `ZWESECUR ### Configure main Zowe server to use client certificate identity mapping -This security configuration is necessary for API ML to be able to map client certificate to a z/OS identity. A user running API Gateway must have read access to the SAF resource `IRR.RUSERMAP` in the `FACILITY` class. -To set up this security configuration, submit the `ZWESECUR` JCL member. For users upgrading from version 1.18 and lower use the following configuration steps. +This security configuration is necessary for API ML to be able to map client certificate to a z/OS identity. A user running API Gateway must have READ access to the SAF resource `IRR.RUSERMAP` in the `FACILITY` class. +To set up this security configuration, submit the `ZWESECUR` JCL member. For users upgrading from version 1.18 and lower use the following configuration steps according to your ESM: -#### Using RACF +
+Click here for procedure details for RACF. If you use RACF, verify and update permission in the `FACILITY` class. **Follow these steps:** -1. Verify user `ZWESVUSR` has read access. +1. Verify user `ZWESVUSR` has READ access. ``` RLIST FACILITY IRR.RUSERMAP AUTHUSER ``` -2. Add user `ZWESVUSR` permission to read. +2. Add user `ZWESVUSR` permission to READ. ``` PERMIT IRR.RUSERMAP CLASS(FACILITY) ACCESS(READ) ID(ZWESVUSR) ``` @@ -562,19 +718,22 @@ If you use RACF, verify and update permission in the `FACILITY` class. SETROPTS RACLIST(FACILITY) REFRESH ``` -#### Using ACF2 +
+ +
+Click here for procedure details for ACF2. If you use ACF2, verify and update permission in the `FACILITY` class. **Follow these steps:** -1. Verify user `ZWESVUSR` has read access. +1. Verify user `ZWESVUSR` has READ access. ``` SET RESOURCE(FAC) LIST LIKE(IRR-) ``` -2. Add user `ZWESVUSR` permission to read. +2. Add user `ZWESVUSR` permission to READ. ``` RECKEY IRR.RUSERMAP ADD(SERVICE(READ) ROLE(&STCGRP.) ALLOW) ``` @@ -584,33 +743,39 @@ If you use ACF2, verify and update permission in the `FACILITY` class. F ACF2,REBUILD(FAC) ``` -#### Using TSS +
+ +
+Click here for procedure details for Top Secret. If you use TSS, verify and update permission in `FACILITY` class. **Follow these steps:** -1. Verify user `ZWESVUSR` has read access. +1. Verify user `ZWESVUSR` has READ access. ``` TSS WHOHAS IBMFAC(IRR.RUSERMAP) ``` -2. Add user `ZWESVUSR` permission to read. +2. Add user `ZWESVUSR` permission to READ. ``` TSS PER(ZWESVUSR) IBMFAC(IRR.RUSERMAP) ACCESS(READ) ``` +
+ ### Configure main Zowe server to use distributed identity mapping -This security configuration is necessary for API ML to be able to map the association between a z/OS user ID and a distributed user identity. A user running the API Gateway must have read access to the SAF resource `IRR.IDIDMAP.QUERY` in the `FACILITY` class. -To set up this security configuration, submit the `ZWESECUR` JCL member. For users upgrading from version 1.28 and lower, use the following configuration steps. +This security configuration is necessary for API ML to map the association between a z/OS user ID and a distributed user identity. A user running the API Gateway must have READ access to the SAF resource `IRR.IDIDMAP.QUERY` in the `FACILITY` class. +To set up this security configuration, submit the `ZWESECUR` JCL member. For users upgrading from version 1.28 and lower, use the following configuration steps according to your ESM: -#### Using RACF +
+Click here for procedure details for RACF. If you use RACF, verify and update permission in the `FACILITY` class. **Follow these steps:** -1. Verify that user `ZWESVUSR` has read access. +1. Verify that user `ZWESVUSR` has READ access. ``` RLIST FACILITY IRR.IDIDMAP.QUERY AUTHUSER ``` @@ -622,7 +787,7 @@ If you use RACF, verify and update permission in the `FACILITY` class. ``` RDEFINE FACILITY IRR.IDIDMAP.QUERY ``` -4. Add user `ZWESVUSR` permission to read. +4. Add user `ZWESVUSR` permission to with READ access. ``` PERMIT IRR.IDIDMAP.QUERY CLASS(FACILITY) ACCESS(READ) ID(ZWESVUSR) ``` @@ -632,19 +797,22 @@ If you use RACF, verify and update permission in the `FACILITY` class. SETROPTS RACLIST(FACILITY) REFRESH ``` -#### Using ACF2 +
+ +
+Click here for procedure details for ACF2. If you use ACF2, verify and update permission in the `FACILITY` class. **Follow these steps:** -1. Verify that user `ZWESVUSR` has read access. +1. Verify that user `ZWESVUSR` has READ access. ``` SET RESOURCE(FAC) LIST LIKE(IRR-) ``` -2. Add user `ZWESVUSR` permission to read. +2. Add user `ZWESVUSR` permission with READ access. ``` RECKEY IRR.IDIDMAP.QUERY ADD(SERVICE(READ) ROLE(&STCGRP.) ALLOW) ``` @@ -653,95 +821,139 @@ If you use ACF2, verify and update permission in the `FACILITY` class. ``` F ACF2,REBUILD(FAC) ``` +
-#### Using TSS +
+Click here for procedure details for Top Secret. If you use TSS, verify and update permission in `FACILITY` class. **Follow these steps:** -1. Verify that user `ZWESVUSR` has read access. +1. Verify that user `ZWESVUSR` has READ access. ``` TSS WHOHAS IBMFAC(IRR.IDIDMAP.QUERY) ``` -2. Add user `ZWESVUSR` permission to read. +2. Add user `ZWESVUSR` permission with READ access. ``` TSS PER(ZWESVUSR) IBMFAC(IRR.IDIDMAP.QUERY) ACCESS(READ) ``` +
+ ### Configure signed SAF Identity tokens (IDT) -This section provides a brief description of how to configure SAF Identity tokens on z/OS so that they can be used by Zowe components like zss or API Mediation layer ([Implement a new SAF IDT provider](../extend/extend-apiml/implement-new-saf-provider.md)) +This section provides a brief description of how to configure SAF Identity tokens on z/OS so that they can be used by Zowe components like zss or API ML. See [Implement a new SAF IDT provider](../extend/extend-apiml/implement-new-saf-provider.md). -Follow these general steps: +**Follow these steps:** -1. Create PKCS#11 token -2. Generate a secret key for the PKCS#11 token (you can use the sample program ZWESECKG in the SZWESAMP dataset) -3. Define a SAF resource profile under the IDTDATA SAF resource class +1. Create a PKCS#11 token. +2. Generate a secret key for the PKCS#11 token (you can use the sample program ZWESECKG in the SZWESAMP dataset). +3. Define a SAF resource profile under the IDTDATA SAF resource class. Details with examples can be found in documentation of external security products: -* **RACF** - **_Signed and Unsigned Identity Tokens_** and **_IDT Configuration_** subsections in _z/OS Security Server RACROUTE Macro Reference_ book, [link](https://www.ibm.com/docs/en/zos/2.4.0?topic=reference-activating-using-idta-parameter-in-racroute-requestverify). -* **Top Secret** - _**Maintain Identity Token (IDT) Records**_ subsection in _Administrating_ chapter, [link](https://techdocs.broadcom.com/us/en/ca-mainframe-software/security/ca-top-secret-for-z-os/16-0/administrating/maintaining-special-security-records/maintain-identity-token-(idt)-records.html). -* **ACF2** - _**IDTDATA Profile Records**_ subsection in _Administrating_ chapter, [link](https://techdocs.broadcom.com/us/en/ca-mainframe-software/security/ca-acf2-for-z-os/16-0/administrating/administer-records/profile-records/idtdata-profile-records.html). + +* **RACF** +See **_Signed and Unsigned Identity Tokens_** and **_IDT Configuration_** subsections in _z/OS Security Server RACROUTE Macro Reference_ in the article [Activating and using the IDTA parameter in RACROUTE REQUEST=VERIFY](https://www.ibm.com/docs/en/zos/2.4.0?topic=reference-activating-using-idta-parameter-in-racroute-requestverify). + +* **ACF2** +See **_IDTDATA Profile Records_** subsection in _Administrating_ chapter, in the article [IDTDATA Profile Records](https://techdocs.broadcom.com/us/en/ca-mainframe-software/security/ca-acf2-for-z-os/16-0/administrating/administer-records/profile-records/idtdata-profile-records.html). + +* **Top Secret** +See **_Maintain Identity Token (IDT) Records_** subsection in _Administrating_ chapter, in the article [Maintain Identity Token (IDT) Records](https://techdocs.broadcom.com/us/en/ca-mainframe-software/security/ca-top-secret-for-z-os/16-0/administrating/maintaining-special-security-records/maintain-identity-token-(idt)-records.html). A part of the Signed SAF Identity token configuration is a nontrivial step that has to generate a secret key for the PKCS#11 token. The secret key is generated in ICSF by calling the PKCS#11 Generate Secret Key (CSFPGSK) or Token Record Create (CSFPTRC) callable services. An example of the CSFPGSK callable service can be found in the SZWESAMP dataset as the ZWESECKG job. ### Configure the main Zowe server to issue SMF records -This security configuration is necessary for API ML to be able to issue SMF records. A user running the API Gateway must have _read_ access to the RACF general resource `IRR.RAUDITX` in the `FACILITY` class. +This security configuration is necessary for API ML to be able to issue SMF records. A user running the API Gateway must have READ access to the RACF general resource `IRR.RAUDITX` in the `FACILITY` class. To set up this security configuration, submit the `ZWESECUR` JCL member. For users upgrading from version 1.18 and lower, use the configuration steps that correspond to the ESM. -To check whether you already have the auditing profile defined, issue the following command and review the output to confirm that the profile exists and that the user `ZWESVUSR` who runs the `ZWESLSTC` started task has `READ` access to this profile. +* To check whether you already have the auditing profile defined, issue the following command and review the output to confirm that the profile exists and that the user `ZWESVUSR` who runs the `ZWESLSTC` started task has READ access to this profile. -- If you use RACF, issue the following command: +
+ Click here for command details for RACF. + + If you use RACF, issue the following command: ``` RLIST FACILITY IRR.RAUDITX AUTHUSER ``` -- If you use Top Secret, issue the following command: +
+ +
+ Click here for command details for ACF2. + + If you use ACF2, issue the following commands: + ``` + SET RESOURCE(FAC) + ``` + ``` + LIST LIKE(IRR-) + ``` + +
+ +
+ Click here for command details for Top Secret. + + If you use Top Secret, issue the following command: ``` TSS WHOHAS IBMFAC(IRR.RAUDITX) ``` -- If you use ACF2, issue the following commands: + +
+ +* If the user `ZWESVUSR` who runs the `ZWESLSTC` started task does not have READ access to this profile, follow the procedure that corresponds to your ESM: + +
+ Click here for procedure details for RACF. + + If you use RACF, update permission in the `FACILITY` class. + + **Follow these steps:** + + 1. Add user `ZWESVUSR` permission to `READ`. + ``` + PERMIT IRR.RAUDITX CLASS(FACILITY) ACCESS(READ) ID(ZWESVUSR) + ``` + 2. Activate changes. + ``` + SETROPTS RACLIST(FACILITY) REFRESH + ``` + +
+ +
+ Click here for command details for ACF2. + + If you use ACF2, add user `ZWESVUSR` permission to `READ`. Issue the following commands: ``` SET RESOURCE(FAC) ``` ``` - LIST LIKE(IRR-) + RECKEY IRR ADD(RAUDITX ROLE(&STCGRP.) SERVICE(READ) ALLOW) + ``` + ``` + F ACF2,REBUILD(FAC) ``` -If the user `ZWESVUSR` who runs the `ZWESLSTC` started task does not have `READ` access to this profile, follow the procedure that corresponds to your ESM: - -- If you use RACF, update permission in the `FACILITY` class. - - **Follow these steps:** - - 1. Add user `ZWESVUSR` permission to `READ`. - ``` - PERMIT IRR.RAUDITX CLASS(FACILITY) ACCESS(READ) ID(ZWESVUSR) - ``` - 2. Activate changes. - ``` - SETROPTS RACLIST(FACILITY) REFRESH - ``` - -- If you use Top Secret, add user `ZWESVUSR` permission to `READ`. Issue the following command: - ``` - TSS PER(ZWESVUSR) IBMFAC(IRR.RAUDITX) ACCESS(READ) - ``` - -- If you use ACF2, add user `ZWESVUSR` permission to `READ`. Issue the following commands: - ``` - SET RESOURCE(FAC) - ``` - ``` - RECKEY IRR ADD(RAUDITX ROLE(&STCGRP.) SERVICE(READ) ALLOW) - ``` - ``` - F ACF2,REBUILD(FAC) - ``` - +
+ +
+ Click here for command details for Top Secret. + + If you use Top Secret, add user `ZWESVUSR` permission to READ. Issue the following command: + ``` + TSS PER(ZWESVUSR) IBMFAC(IRR.RAUDITX) ACCESS(READ) + ``` + +
+ + + For more information about SMF records, see [SMF records](../user-guide/api-mediation/api-mediation-smf.md) in the Using Zowe API Mediation Layer documentation. + ### Multi-Factor Authentication (MFA) Multi-factor authentication is supported for several components, such as the Desktop and API Mediation Layer. @@ -753,8 +965,6 @@ Multi-factor authentication is provided by third-party products which Zowe is co :::note Notes * To support the multi-factor authentication, it is necessary to apply z/OSMF APAR [PH39582](https://www.ibm.com/support/pages/apar/PH39582). -* For information on using MFA in Zowe, see [Multi-Factor Authentication](mvd-configuration.md#multi-factor-authentication-configuration). - * MFA must work with Single-Sign-On (SSO). Make sure that [SSO](#single-sign-on-sso) is configured before you use MFA in Zowe. ::: @@ -768,5 +978,4 @@ Zowe has an SSO scheme with the goal that each time you use multiple Zowe compon ### API Mediation Layer OIDC Authentication -Zowe requires ACF2 APAR LU01316 to be applied when using the ACF2 security manager. - +Zowe requires ACF2 APAR LU01316 to be applied when using the ACF2 security manager. \ No newline at end of file diff --git a/versioned_docs/version-v2.18.x/user-guide/configure-zowe-runtime.md b/versioned_docs/version-v2.18.x/user-guide/configure-zowe-runtime.md index bc95048b0c..565f3d31bb 100644 --- a/versioned_docs/version-v2.18.x/user-guide/configure-zowe-runtime.md +++ b/versioned_docs/version-v2.18.x/user-guide/configure-zowe-runtime.md @@ -10,14 +10,14 @@ Use one of the following options to initialize Zowe z/OS runtime: * Initialize Zowe maunually using zwe init command group * Configure Zowe with z/OSMF workflows -## Initialize Zowe maunually using zwe init command group +## Initialize Zowe manually using zwe init command group After your installation of Zowe runtime, you can run the `zwe init` command to perform the following configurations: * Initialize Zowe with copies of data sets provided with Zowe -* Create user IDs and security manager settings -* Provide APF authorize load libraries -* Configure Zowe to use TLS certificates +* Create user IDs and security manager settings (Security Admin) +* Provide APF authorize load libraries (Security Admin) +* Configure Zowe to use TLS certificates (Security Admin) * Configure VSAM files to run the Zowe caching service used for high availability (HA) * Configure the system to launch the Zowe started task diff --git a/versioned_docs/version-v2.18.x/user-guide/configuring-overview.md b/versioned_docs/version-v2.18.x/user-guide/configuring-overview.md index d2f4ab568c..44654c5947 100644 --- a/versioned_docs/version-v2.18.x/user-guide/configuring-overview.md +++ b/versioned_docs/version-v2.18.x/user-guide/configuring-overview.md @@ -23,12 +23,12 @@ To cofigure Zowe runtime, choose from the following options: * **Option 1: Configure Zowe manually using the `zwe init` command group** To run the `zwe init` command, it is necessary to create a Zowe configuration file. For more information about this file, see the [Runtime directory](./installandconfig.md#runtime-directory) which details all of the started tasks in the article _Preparing for installation_. -Once your configuration file is prepared, see [Configuring Zowe with zwe init](./initialize-zos-system.md), for more information about using the `zwe init` command group. + Once your configuration file is prepared, see [Configuring Zowe with zwe init](./initialize-zos-system.md), for more information about using the `zwe init` command group. * **Option 2: Configure Zowe with z/OSMF workflows** You can execute the Zowe configuration workflow either from a PSWI during deployment, or later from a created software instance in z/OSMF. Alternatively, you can execute the configuration workflow z/OSMF during the workflow registration process. -For more information, see [Configure Zowe with z/OSMF Workflows](./configure-zowe-zosmf-workflow.md). + For more information, see [Configure Zowe with z/OSMF Workflows](./configure-zowe-zosmf-workflow.md). ## Configuring the z/OS system for Zowe diff --git a/versioned_docs/version-v2.18.x/user-guide/configuring-security.md b/versioned_docs/version-v2.18.x/user-guide/configuring-security.md index 8f9adc9c77..3a289f64d0 100644 --- a/versioned_docs/version-v2.18.x/user-guide/configuring-security.md +++ b/versioned_docs/version-v2.18.x/user-guide/configuring-security.md @@ -2,7 +2,12 @@ During the initial installation of Zowe server-side components, it is necessary for your organization's security administrator to perform a range of tasks that require elevated security permissions. As a security administrator, follow the procedures outlined in this article to configure Zowe and your z/OS system to run Zowe with z/OS. -:::info Required roles: system programmer, security administrator +:::info Required role: security administrator (elevated permissions required) +::: + +:::note +For initial tasks to be performed by the security administrator before Zowe server-side installation, see [Addressing security requirements](./address-security-requirements.md). + ::: ## Validate and re-run `zwe init` commands @@ -11,24 +16,104 @@ During installation, the system programmer customizes values in the zowe.yaml fi ## Initialize Zowe security configurations +This security configuration step is required for first time setup of Zowe and may require security authorization. If Zowe has already been launched on a z/OS system from a previous release of Zowe v2, and the `zwe init security` subcommand successfully ran when initializing the z/OS subsystem, you can skip this step unless told otherwise in the release documentation. + Choose from the following methods to initialize Zowe security configurations: -* Configuring with `zwe init security` -* Configuring with `ZWESECUR` JCL +
+Click here to configure with the `zwe init security` command. + +**Configure with `zwe init security` command** + +The `zwe init security` command reads data from `zowe.yaml` and constructs a JCL member using `ZWESECUR` as a template which is then submitted. This is a convenience step to assist with driving Zowe configuration through a pipeline or when you prefer to use USS commands rather than directly edit and customize JCL members. + +:::note +If you do not have permissions to update your security configurations, use the `security-dry-run` described in the following tip. We recommend you inform your security administrator to review the `ZWESECUR` job content. +::: + +:::tip + +To avoid having to run the `init security` command, you can specify the parameter `--security-dry-run`. This parameter enables you to construct a JCL member containing the security commmands without running the member. This is useful for previewing commands and can also be used to copy and paste commands into a TSO command prompt for step by step manual execution. + +**Example:** + +``` +#>zwe init security -c ./zowe.yaml --security-dry-run +------------------------------------------------------------------------------- +>> Run Zowe security configurations +Modify ZWESECUR +- IBMUSER.ZWEV2.CUST.JCLLIB(ZW134428) is prepared +Dry-run mode, security setup is NOT performed on the system. +Please submit IBMUSER.ZWEV2.CUST.JCLLIB(ZW134428) manually. +>> Zowe security configurations are applied successfully. +#> +``` +::: + +
+ + + +
+Click here to configure with `ZWESECUR` JCL. + + +**Configure with `ZWESECUR` JCL** -For more information about both of these methods, see [Initialize Zowe security configurations](./initialize-security-configuration.md). +An alternative to using `zwe init security` is to prepare a JCL member to configure the z/OS system, and edit `ZWESECUR` to make changes. + +The JCL allows you to vary which security manager you use by setting the _PRODUCT_ variable to be one of the following ESMs: +* `RACF` +* `ACF2` +* `TSS`. + +**Example:** +``` +// SET PRODUCT=RACF * RACF, ACF2, or TSS +``` + +If `ZWESECUR` encounters an error or a step that has already been performed, it continues to the end, so it can be run repeatedly in a scenario such as a pipeline automating the configuration of a z/OS environment for Zowe installation. + +:::info Important +It is expected that your security administrator will be required to review, edit where necessary, and either execute `ZWESECUR` as a single job, or execute individual TSO commands to complete the security configuration of a z/OS system in preparation for installing and running Zowe. +::: + +The following video shows how to locate the `ZWESECUR` JCL member and execute it. + + + +
+ + +:::tip + +If an error occured in performing security configuration, these configurations can be undone. +
+Click here for details about undoing security configurations. + + +To undo all of the z/OS security configuration steps performed by the JCL member `ZWESECUR`, use the reverse member `ZWENOSEC`. This member contains steps that reverse steps performed by `ZWESECUR`. This is useful in the following situations: + +- You are configuring z/OS systems as part of a build pipeline that you want to undo, and redo configuration and installation of Zowe using automation. +- You configured a z/OS system for Zowe that you no longer want to use, and you prefer to delete the Zowe user IDs and undo the security configuration settings rather than leave them enabled. + +If you run `ZWENOSEC` on a z/OS system, it is necessary to rerun `ZWESECUR` to reinitialize the z/OS security configuration. Zowe cannot be run until `ZWESECUR` is rerun. + +
+ +::: ## Perform APF authorization of load libraries Zowe contains load modules that require access to make privileged z/OS security manager calls. These load modules are held in two load libraries which must be APF authorized. For more information about how to issue the `zwe init apfauth` command to perform APF authority commands, see [Performing APF authorization of load libraries](./apf-authorize-load-library.md). -## Configure the z/OS system for Zowe +## Customize security of your z/OS system -Review and perform z/OS configuration steps based on your settings. For a detailed table of configuration procedures and associated purposes for performing these procedures, see [Configuring the z/OS system for Zowe](./configure-zos-system.md). +Review and perform z/OS configuration steps based on your settings. For a detailed table of configuration procedures and associated purposes for performing these procedures, see [Customizing z/OS system security](./configure-zos-system.md). ## Assign security permissions to users -Assign users (ZWESVUSR and ZWESIUSR) and the ZWEADMIN security group permissions required to perform specific tasks. For more information see, [Assign security permissions to users](./assign-security-permissions-to-users.md). +Assign users (ZWESVUSR and ZWESIUSR) and the ZWEADMIN security group permissions required to perform specific tasks. For more information see, [Assigning security permissions to users](./assign-security-permissions-to-users.md). ## Zowe Feature specific configuration tasks @@ -48,7 +133,7 @@ Depending on the specific Zowe server-side components that your organization is ## Next step -After these aforementioned security configuration steps are completed, the next step is to [install Zowe main started tasks](./zwe-init-subcommand-overview.md#installing-zowe-main-started-tasks-zwe-init-stc). +After Zowe z/OS runtime is initialized, and you complete other procedures in the Configuring security section, the next step is [Configuring certificates](./configure-certificates.md). \ No newline at end of file diff --git a/versioned_docs/version-v2.18.x/user-guide/initialize-zos-system.md b/versioned_docs/version-v2.18.x/user-guide/initialize-zos-system.md index 02006b7959..587b848eea 100644 --- a/versioned_docs/version-v2.18.x/user-guide/initialize-zos-system.md +++ b/versioned_docs/version-v2.18.x/user-guide/initialize-zos-system.md @@ -23,7 +23,7 @@ Configures the VSAM files needed to run the Zowe caching service used for high a Configures the system to launch the Zowe started task. :::info Recommendation: -We recommend you to run these sub commands one by one to clearly see the output of each step. To successfully run `zwe init security`, `zwe init apfauth`, and `zwe init certificate`, it is likely that your organization requires elevated permissions. We recommend you consult with your security administrator to run these commands. For more information about tasks for the security administrator, see the section [Configuring security](./configuring-security.md) in this configuration documentation. +We recommend you to run these sub commands one by one to clearly see the output of each step. To successfully run `zwe init security`, `zwe init apfauth`, and `zwe init certificate`, it is likely that your organization requires elevated permissions. We recommend you consult with your security administrator to run these commands. For more information about tasks for the security administrator, and details about the `zwe init security` command, see the section [Configuring security](./configuring-security.md) in this configuration documentation ::: :::tip diff --git a/versioned_docs/version-v2.18.x/user-guide/systemrequirements-zos.md b/versioned_docs/version-v2.18.x/user-guide/systemrequirements-zos.md index 86ade0b307..7a2d8fe15f 100644 --- a/versioned_docs/version-v2.18.x/user-guide/systemrequirements-zos.md +++ b/versioned_docs/version-v2.18.x/user-guide/systemrequirements-zos.md @@ -107,3 +107,7 @@ Zowe consumption reference data were measured with the default Zowe configuratio - For production use of Zowe, we recommend configuring z/OSMF to leverage Zowe functionalities that require z/OSMF. For more information, see [Configuring z/OSMF](systemrequirements-zosmf.md). - For non-production use of Zowe (such as development, proof-of-concept, demo), you can customize the configuration of z/OSMF to create **_z/OS MF Lite_** to simplify your setup of z/OSMF. z/OS MF Lite only supports selected REST services (JES, DataSet/File, TSO and Workflow), resulting in considerable improvements in startup time as well as a reduction in steps to set 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). ::: + +:::note +For specific z/OS security configuration options that apply to the specific Zowe server-side components in your configuration, see [Customizing z/OS system security](./configure-zos-system.md). +::: \ No newline at end of file diff --git a/versioned_docs/version-v2.18.x/user-guide/verify-zowe-runtime-install.md b/versioned_docs/version-v2.18.x/user-guide/verify-zowe-runtime-install.md index 8af891f364..8c98e29208 100644 --- a/versioned_docs/version-v2.18.x/user-guide/verify-zowe-runtime-install.md +++ b/versioned_docs/version-v2.18.x/user-guide/verify-zowe-runtime-install.md @@ -1,9 +1,9 @@ # Verifying Zowe installation on z/OS -After the Zowe™ started task `ZWESLSTC` is running, follow the instructions in the following sections to verify that the components are functional. +After the Zowe™ started task `ZWESLSTC` is running, follow the procedures applicable to your installation to verify that the components are functional. - [Verifying Zowe Application Framework installation](#verifying-zowe-application-framework-installation) -- [Verifying API Mediation installation](#verifying-api-mediation-installation) +- [Verifying API Mediation Layer installation](#verifying-api-mediation-layer-installation) - [Verifying z/OS Services installation](#verifying-zos-services-installation) :::note @@ -23,17 +23,19 @@ If the Zowe Application Framework is installed correctly, you can open the Zowe From a supported browser, open the Zowe Desktop at `https://myhost:httpsPort` -where, +where: -- _myHost_ is the host on which you installed the Zowe Application Server. -- _httpsPort_ is the port number value `components.app-server.port` in `zowe.yaml`. For more information, see [Configure component app-server](../appendix/zowe-yaml-configuration#configure-component-app-server). +- **_myHost_** +is the host on which you installed the Zowe Application Server. +- **_httpsPort_** +is the port number value `components.app-server.port` in `zowe.yaml`. For more information, see [Configure component app-server](../appendix/zowe-yaml-configuration#configure-component-app-server). For example, if the Zowe Application Server runs on host _myhost_ and the port number that is assigned to `components.app-server.port` is 12345, you specify `https://myhost:12345`. The web desktop uses page direct to the actual initial page which is `https://myhost:12345/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html`. If the redirect fails, try the full URL. If the desktop appears but you are unable to log on, check [Cannot log into the Zowe desktop](../troubleshoot/app-framework/app-troubleshoot.md#cannot-log-in-to-the-zowe-desktop) for troubleshooting tips. -## Verifying API Mediation installation +## Verifying API Mediation Layer installation Use your preferred REST API client to review the value of the status variable of the API Catalog service that is routed through the API Gateway using the following URL: @@ -41,29 +43,33 @@ Use your preferred REST API client to review the value of the status variable of https://myhost:httpsPort/apicatalog/api/v1/application/health ``` -where, +where: -- _myHost_ is the host on which you installed the Zowe API Mediation Layer. -- _httpsPort_ is the port number value `zowe.externalPort` in `zowe.yaml`. For more information, see [Domain and port to access Zowe](../appendix/zowe-yaml-configuration#domain-and-port-to-access-zowe). +- **_myHost_** +is the host on which you installed the Zowe API Mediation Layer. +- **_httpsPort_** +is the port number value `zowe.externalPort` in `zowe.yaml`. For more information, see [Domain and port to access Zowe](../appendix/zowe-yaml-configuration#domain-and-port-to-access-zowe). **Example:** -The following example illustrates how to use the **curl** utility to invoke API Mediation Layer endpoint and the **grep** utility to parse out the response status variable value. The `curl` command is a powerful tool used for making HTTP requests from the command line. It allows you to send and receive data from various protocols, including HTTP, HTTPS, FTP, and more. +The following example illustrates how to use the **curl** utility to invoke an API Mediation Layer endpoint and the **grep** utility to parse out the response status variable value. The `curl` command is a powerful tool used for making HTTP requests from the command line. It allows you to send and receive data from various protocols, including HTTP, HTTPS, FTP, and more. ``` $ curl -v -k --silent https://myhost:httpsPort/apicatalog/api/v1/application/health 2>&1 | awk '/"status":"UP"/' | awk -F\" '{print$4;}' UP ``` -- `-v`: The `-v` option stands for "verbose." When you include this option, curl provides more detailed information during the request and response process. It displays additional information such as the request headers, response headers, and other debugging details. +- **`-v`** +The `-v` option stands for "verbose." When you include this option, curl provides more detailed information during the request and response process. It displays additional information such as the request headers, response headers, and other debugging details. -- `-k`: The `-k` option stands for "insecure" or "insecure SSL." When you include this option, curl allows insecure connections and bypasses SSL certificate verification. It is useful when making requests to HTTPS URLs with self-signed certificates or when dealing with SSL certificate issues. However, it's important to note that using `-k` removes security checks and may expose you to potential security risks. Exercise caution when using this option, especially in production environments. +- **`-k`** +The `-k` option stands for "insecure" or "insecure SSL." When you include this option, curl allows insecure connections and bypasses SSL certificate verification. It is useful when making requests to HTTPS URLs with self-signed certificates or when dealing with SSL certificate issues. However, it is important to note that using `-k` removes security checks and may expose you to potential security risks. Exercise caution when using this option, especially in production environments. -The response `UP` confirms that API Mediation Layer is installed and is running properly. For more instructions about `curl` command, please see the [tutorial](https://curl.se/docs/manual.html). +The response `UP` confirms that API Mediation Layer is installed and is running properly. For more instructions about `curl` command, see the [tutorial](https://curl.se/docs/manual.html). ## Verifying z/OS Services installation -Zowe z/OS services usually are registered with Zowe APIML Discovery and exposed with certain service url like `//api/v1`. +Zowe z/OS services usually are registered with Zowe API ML Discovery and exposed with a certain service url like `//api/v1`. Here we give an example of verifying `jobs-api` shipped with Zowe. Please be aware that `jobs-api` is not enabled by default if you created your Zowe configuration file from `example-zowe.yaml`. To enable `jobs-api`, you need to set `components.jobs-api.enabled` to be `true` and restart Zowe. You can verify the installation of `jobs-api` service from an internet browser by entering the following case-sensitive URL: @@ -71,8 +77,9 @@ Here we give an example of verifying `jobs-api` shipped with Zowe. Please be awa https://hostName:gatewayPort/jobs/api/v1/jobs?prefix=* ``` -where, +where: -`gatewayPort` is the port number that is assigned to `zowe.externalPort` in the `zowe.yaml` file used to launch Zowe. For more information, see [Domain and port to access Zowe](../appendix/zowe-yaml-configuration#domain-and-port-to-access-zowe). +* **`gatewayPort`** +is the port number that is assigned to `zowe.externalPort` in the `zowe.yaml` file used to launch Zowe. For more information, see [Domain and port to access Zowe](../appendix/zowe-yaml-configuration#domain-and-port-to-access-zowe). The above link should prompt you to login. After you input correct user name and password of your target z/OS system, you should see JSON format data of all jobs running on the system. diff --git a/versioned_docs/version-v2.18.x/user-guide/zos-components-installation-checklist.md b/versioned_docs/version-v2.18.x/user-guide/zos-components-installation-checklist.md index 2e3840d970..fb137690f5 100644 --- a/versioned_docs/version-v2.18.x/user-guide/zos-components-installation-checklist.md +++ b/versioned_docs/version-v2.18.x/user-guide/zos-components-installation-checklist.md @@ -33,7 +33,7 @@ Configure Zowe and your z/OS system to run Zowe with z/OS. | Task | Results | Time Estimate | |--------------------|----|------| |[Review Configuring security](./configuring-security.md) | Knowledge about which tasks need to be performed by the security administrator. | 10 minutes| -[Initialize Zowe security configurations](./initialize-security-configuration) | The JCL member to configure the z/OS system is created. | 10 minutes | +[Initialize Zowe security configurations](./configuring-security.md) | The JCL member to configure the z/OS system is created. | 10 minutes | [Perform APF authorization of load libraries](./apf-authorize-load-library.md) | APF authorization is granted to load libraries. | 10 minutes | [Address z/OS requirements for Zowe](./configure-zos-system.md) | Your z/OS and security product are configured. | 2 hours | [Assign security permissions to users](./assign-security-permissions-to-users.md) | Zowe user is created and is assigned all required permissions. | 30 minutes | @@ -82,7 +82,7 @@ You can configure your system to enable HA. This configuration is not required t | Verification Step | Task | Results | Time Estimate | |----|-----------|----|-------------| | [Verify Zowe Application Framework installation](../user-guide/verify-zowe-runtime-install.md#verifying-zowe-application-framework-installation) | Open the Zowe Desktop from a supported browser | You should be able to open the Zowe Desktop from a supported browser. | 20 minutes| -| [Verify API Mediation installation](../user-guide/verify-zowe-runtime-install.md#verifying-api-mediation-installation) |Use a REST API client to review the value of the status variable of the API Catalog service routed through the API Gateway | See the example presented in Verify API Mediation installation | 15 minutes | +| [Verify API Mediation installation](../user-guide/verify-zowe-runtime-install.md#verifying-api-mediation-layer-installation) |Use a REST API client to review the value of the status variable of the API Catalog service routed through the API Gateway | See the example presented in Verify API Mediation installation | 15 minutes | |[Verify z/OS Services installation](../user-guide/verify-zowe-runtime-install.md#verifying-zos-services-installation) |Zowe z/OS services usually are registered with Zowe APIML Discovery| You should see JSON format data of all jobs running on the system | 15 minutes | diff --git a/versioned_docs/version-v2.18.x/user-guide/zwe-init-subcommand-overview.md b/versioned_docs/version-v2.18.x/user-guide/zwe-init-subcommand-overview.md index 7ded39da9f..62a303484c 100644 --- a/versioned_docs/version-v2.18.x/user-guide/zwe-init-subcommand-overview.md +++ b/versioned_docs/version-v2.18.x/user-guide/zwe-init-subcommand-overview.md @@ -6,12 +6,12 @@ Review this article to learn about the individual subcommands executed in `zwe i Some of the following `zwe init` subcommands require elevated permissions. See the required roles associated with each of these commands. ::: -* [Initializing Zowe custom data sets (`zwe init mvs`)](#initializing-zowe-custom-data-sets-zwe-init-mvs) -* [Initializing Zowe security configurations (`zwe init security`)](#initializing-zowe-security-configurations-zwe-init-security) -* [Performing APF authorization of load libraries (`zwe init apfauth`)](#performing-apf-authorization-of-load-libraries-zwe-init-apfauth) -* [Configuring Zowe to use TLS certificates (`zwe init certificate`)](#configuring-zowe-to-use-tls-certificates-zwe-init-certificate) -* [Creating VSAM caching service datasets (`zwe init vsam`)](#creating-vsam-caching-service-datasets-zwe-init-vsam) -* [Installing Zowe main started tasks (`zwe init stc`)](#installing-zowe-main-started-tasks-zwe-init-stc) +- [Initializing Zowe custom data sets (`zwe init mvs`)](#initializing-zowe-custom-data-sets-zwe-init-mvs) + - [Procedure to initialize Zowe custom data sets](#procedure-to-initialize-zowe-custom-data-sets) +- [Initializing Zowe security configurations (`zwe init security`)](#initializing-zowe-security-configurations-zwe-init-security) +- [Performing APF authorization of load libraries (`zwe init apfauth`)](#performing-apf-authorization-of-load-libraries-zwe-init-apfauth) +- [Configuring Zowe to use TLS certificates (`zwe init certificate`)](#configuring-zowe-to-use-tls-certificates-zwe-init-certificate) +- [Installing Zowe main started tasks (`zwe init stc`)](#installing-zowe-main-started-tasks-zwe-init-stc) ## Initializing Zowe custom data sets (`zwe init mvs`) @@ -29,7 +29,7 @@ The contents of these data sets represent the original files that were provided For modification and execution, it is necessary to create custom data sets by using the `zwe init mvs` command. For detailed information about this command, see the [`zwe init mvs` command reference](../appendix/zwe_server_command_reference/zwe/init/zwe-init-mvs). -The `zowe.yaml` section that contains the parameters for the data set names is: +The folowing `zowe.yaml` section contains the parameters for the data set names: ```yaml zowe: @@ -84,7 +84,7 @@ Copy components/launcher/bin/zowe_launcher to USER.ZWEV2.SZWEAUTH(ZWELNCH) Successful execution of `zwe init mvs` has the following results: -* In the `zowe.yaml` file, three custom data sets are created that have matching values with the follwoing libraries: +* In the `zowe.yaml` file, three custom data sets are created that have matching values with the following libraries: * `zowe.setup.dataset.parmlib` * `zowe.setup.dataset.jcllib` * `zowe.setup.dataset.authPluginLib`. @@ -109,7 +109,31 @@ If Zowe has already been launched on a z/OS system from a previous release of Zo The JCL member `.SZWESAMP(ZWESECUR)` is provided to assist with the security configuration. Before submitting the `ZWESECUR` JCL member, customize this member to match site security rules. For script driven scenarios, you can run the command `zwe init security` which uses `ZWESECUR` as a template to create a customized member in `.CUST.JCLLIB`. This member contains the commands required to perform the security configuration. -For more information about `zwe init security`, see [Initializing Zowe security configurations](./initialize-security-configuration). +For more information about `zwe init security`, see: + +* _Configure with `zwe init security` command_ in [Configuring security](./configuring-security.md). +* [`zwe init security`](../appendix/zwe_server_command_reference/zwe/init/zwe-init-security.md) in the Reference section. + +:::tip + +To avoid having to run the `init security` command, you can specify the flag `--security-dry-run`. This flag enables you to construct a JCL member containing the security commmands without running the member. This is useful for previewing commands and can also be used to copy and paste commands into a TSO command prompt for step by step manual execution. + +**Example:** + +``` +#>zwe init security -c ./zowe.yaml --security-dry-run +------------------------------------------------------------------------------- +>> Run Zowe security configurations +Modify ZWESECUR +- IBMUSER.ZWEV2.CUST.JCLLIB(ZW134428) is prepared +Dry-run mode, security setup is NOT performed on the system. +Please submit IBMUSER.ZWEV2.CUST.JCLLIB(ZW134428) manually. +>> Zowe security configurations are applied successfully. +#> +``` +For production environments, inform your security administrator to re-submit the `init security` command with proper authorization. + +::: ## Performing APF authorization of load libraries (`zwe init apfauth`) @@ -126,7 +150,33 @@ Specifies the user custom load library, containing the ZWELNCH, ZWESIS01 and ZWE * **zowe.setup.dataset.authPluginLib** References the load library for ZIS plugins. -For more information about `zwe init apfauth` see [Performing APF authorization of load libraries](./apf-authorize-load-library). +For more information about `zwe init apfauth` see: +* [Performing APF authorization of load libraries](./apf-authorize-load-library). +* [`zwe init apfauth`](../appendix/zwe_server_command_reference/zwe/init/zwe-init-apfauth.md) in the Reference section. + +:::tip + +To avoid having to run the `init apfauth` command, you can specify the flag `--security-dry-run` as in the following example. + +**Example:** + +``` +zwe init apfauth --security-dry-run -c /path/to/zowe.yaml +------------------------------------------------------------------------------- +>> APF authorize load libraries +APF authorize IBMUSER.ZWEV2.SZWEAUTH +- Dry-run mode, security setup is NOT performed on the system. + Please apply this operator command manually: + SETPROG APF,ADD,DSNAME=IBMUSER.ZWEV2.SZWEAUTH,SMS +APF authorize IBMUSER.ZWEV2.CUST.ZWESAPL +- Dry-run mode, security setup is NOT performed on the system. + Please apply this operator command manually: + SETPROG APF,ADD,DSNAME=IBMUSER.ZWEV2.CUST.ZWESAPL,SMS +>> Zowe load libraries are APF authorized successfully. +``` +For production environments, inform your security administrator to re-submit the `init apfauth` command with proper authorization. + +::: ## Configuring Zowe to use TLS certificates (`zwe init certificate`) @@ -137,7 +187,9 @@ Zowe uses digital certificates for secure, encrypted network communication over Zowe supports using either file-based (PKCS12) or z/OS key ring-based (when on z/OS) keystores and truststores, and can reuse compatible stores. You can use the `zwe init certificate` command to create keystores and truststores by either generating certificates or by allowing users to import their own compatible certificates. -For more information, see [Configuring certificates](./configure-certificates). +For more information about `init certificate`, see: +* [Configuring certificates](./configure-certificates). +* [`zwe init certificate`](../appendix/zwe_server_command_reference/zwe/init/zwe-init-certificate.md) in the Reference section. ## Creating VSAM caching service datasets (`zwe init vsam`) diff --git a/versioned_sidebars/version-v2.18.x-sidebars.json b/versioned_sidebars/version-v2.18.x-sidebars.json index fef86e4c45..8c7df5d498 100644 --- a/versioned_sidebars/version-v2.18.x-sidebars.json +++ b/versioned_sidebars/version-v2.18.x-sidebars.json @@ -233,7 +233,6 @@ "id": "user-guide/configuring-security" }, "items": [ - "user-guide/initialize-security-configuration", "user-guide/apf-authorize-load-library", "user-guide/configure-zos-system", "user-guide/assign-security-permissions-to-users" From 8ad632d8a39d14eb9fcdd6b03adb38459153e70c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Wed, 27 Nov 2024 10:02:57 +0100 Subject: [PATCH 50/67] markdown linter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../configuring-at-tls-for-zowe-server.md | 2 +- docs/user-guide/install-zowe-pswi-acquire.md | 6 ++++-- docs/user-guide/install-zowe-pswi.md | 15 ++++++++------- .../configuring-at-tls-for-zowe-server.md | 4 ++-- .../user-guide/install-zowe-pswi-acquire.md | 6 ++++-- .../user-guide/install-zowe-pswi.md | 15 ++++++++------- 6 files changed, 27 insertions(+), 21 deletions(-) diff --git a/docs/user-guide/configuring-at-tls-for-zowe-server.md b/docs/user-guide/configuring-at-tls-for-zowe-server.md index e65749fa80..8f4e94b399 100644 --- a/docs/user-guide/configuring-at-tls-for-zowe-server.md +++ b/docs/user-guide/configuring-at-tls-for-zowe-server.md @@ -385,7 +385,7 @@ TTLSRule ZoweServerRule { LocalAddr All RemoteAddr All - LocalPortRange 7554-7559 # Range covers all possible Zowe services + LocalPortRange 7551-7559 # Range covers all possible Zowe services Jobname ZWE1* Direction Inbound TTLSGroupActionRef ServerGroupAction diff --git a/docs/user-guide/install-zowe-pswi-acquire.md b/docs/user-guide/install-zowe-pswi-acquire.md index 1714d8e0b6..ad47470f65 100644 --- a/docs/user-guide/install-zowe-pswi-acquire.md +++ b/docs/user-guide/install-zowe-pswi-acquire.md @@ -21,7 +21,8 @@ To acquire the portable software instance, you can download it from the Zowe Dow 2. Download the latest version of the package to your workstation. 3. Use an file transfer utility such as an FTP client to transfer the single pax file to the mainframe. 4. Execute the JCL to unpack the installation file and restore the individual pax files. Sample JCL follows: -``` + +```jcl //USSBATCH EXEC PGM=BPXBATCH //STDOUT DD SYSOUT=* //STDERR DD SYSOUT=* @@ -30,7 +31,8 @@ To acquire the portable software instance, you can download it from the Zowe Dow pax -rvf yourpaxfilename.ZOSMF.pax.Z /* ``` -5. Customize the sample JCL as follows and then submit for execution: + +1. Customize the sample JCL as follows and then submit for execution: 1. Add a JOB statement. 2. Update the USS directory (*yourUSSpaxdirectory*) with the path name where you want to copy the pax file. diff --git a/docs/user-guide/install-zowe-pswi.md b/docs/user-guide/install-zowe-pswi.md index e8d58e1901..3bb273b299 100644 --- a/docs/user-guide/install-zowe-pswi.md +++ b/docs/user-guide/install-zowe-pswi.md @@ -3,7 +3,7 @@ As a systems programmer, your responsibilities include acquiring, installing, maintaining, and configuring mainframe products on your systems. z/OSMF lets you perform these tasks. z/OSMF lets you manage software on your z/OS systems through a browser at any time, from any location. By streamlining some traditional tasks and automating others, z/OSMF can simplify some areas of system management and also reduce the level of expertise that is required for managing system activities. Experienced users can view, define, and update policies that affect system behavior, monitor system performance, and manage their z/OS software. As products and vendors adopt z/OSMF services, you can install and maintain all your mainframe products in a common way according to industry best practices. After configuration is complete, you can execute the product and easily provision new software instances for use on other systems throughout your environment. -## End-to-end installation diagram +## End-to-end installation diagram ![PSWI installation diagram](../images/install/PSWI-install.png) @@ -19,19 +19,20 @@ To install Zowe using z/OSMF, ensure that you meet the following requirements: Refer to the following subpages to guide you through the installation procedure using z/OSMF. -* [Address z/OSMF Requirements](./install-zowe-pswi-address-requirements.md) +- [Address z/OSMF Requirements](./install-zowe-pswi-address-requirements.md) Provides information about z/OSMF general configuration and security requirements. -* [Acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire.md) +- [Acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire.md) Provides the steps to acquire the product software by downloading the z/OSMF portable software instance to the z/OSMF host. You must then register the portable software instance in z/OSMF. -* [Install Product Software Using z/OSMF Deployments](./install-zowe-pswi-deployment.md) +- [Install Product Software Using z/OSMF Deployments](./install-zowe-pswi-deployment.md) Provides the steps to install (deploy) the portable software instance to an LPAR using z/OSMF Deployments. This step creates the SMP/E environment and runs the RECEIVE, APPLY, and ACCEPT steps to prepare the software instance for SMP/E operations. This step also: - * Customizes the data set names that are defined to SMP/E. - * Mounts required USS files if necessary. - * Performs workflow execution to customize the deployed runtime environment for use on a specific z/OS system. + +- Customizes the data set names that are defined to SMP/E. +- Mounts required USS files if necessary. +- Performs workflow execution to customize the deployed runtime environment for use on a specific z/OS system. When these tasks are completed, you are ready to install preventive maintenance. diff --git a/versioned_docs/version-v2.18.x/user-guide/configuring-at-tls-for-zowe-server.md b/versioned_docs/version-v2.18.x/user-guide/configuring-at-tls-for-zowe-server.md index 0f3f56ca33..8806609461 100644 --- a/versioned_docs/version-v2.18.x/user-guide/configuring-at-tls-for-zowe-server.md +++ b/versioned_docs/version-v2.18.x/user-guide/configuring-at-tls-for-zowe-server.md @@ -209,7 +209,7 @@ TTLSRule ApimlClientRule LocalAddr All LocalPortRange 1024-65535 RemoteAddr All - RemotePortRange 7551-7555 # Range covers API ML services (gateway, discovery, api catalog, caching service) + RemotePortRange 7551-7559 # Range covers API ML services (gateway, discovery, api catalog, caching service) Jobname ZWE1A* # Generate according to zowe.job.prefix in zowe.yaml Direction Outbound TTLSGroupActionRef ClientGroupAction @@ -393,7 +393,7 @@ TTLSRule ZoweServerRule { LocalAddr All RemoteAddr All - LocalPortRange 7554-7559 # Range covers all possible Zowe services + LocalPortRange 7551-7559 # Range covers all possible Zowe services Jobname ZWE1* Direction Inbound TTLSGroupActionRef ServerGroupAction diff --git a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-acquire.md b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-acquire.md index 1714d8e0b6..ad47470f65 100644 --- a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-acquire.md +++ b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-acquire.md @@ -21,7 +21,8 @@ To acquire the portable software instance, you can download it from the Zowe Dow 2. Download the latest version of the package to your workstation. 3. Use an file transfer utility such as an FTP client to transfer the single pax file to the mainframe. 4. Execute the JCL to unpack the installation file and restore the individual pax files. Sample JCL follows: -``` + +```jcl //USSBATCH EXEC PGM=BPXBATCH //STDOUT DD SYSOUT=* //STDERR DD SYSOUT=* @@ -30,7 +31,8 @@ To acquire the portable software instance, you can download it from the Zowe Dow pax -rvf yourpaxfilename.ZOSMF.pax.Z /* ``` -5. Customize the sample JCL as follows and then submit for execution: + +1. Customize the sample JCL as follows and then submit for execution: 1. Add a JOB statement. 2. Update the USS directory (*yourUSSpaxdirectory*) with the path name where you want to copy the pax file. diff --git a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi.md b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi.md index e8d58e1901..3bb273b299 100644 --- a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi.md +++ b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi.md @@ -3,7 +3,7 @@ As a systems programmer, your responsibilities include acquiring, installing, maintaining, and configuring mainframe products on your systems. z/OSMF lets you perform these tasks. z/OSMF lets you manage software on your z/OS systems through a browser at any time, from any location. By streamlining some traditional tasks and automating others, z/OSMF can simplify some areas of system management and also reduce the level of expertise that is required for managing system activities. Experienced users can view, define, and update policies that affect system behavior, monitor system performance, and manage their z/OS software. As products and vendors adopt z/OSMF services, you can install and maintain all your mainframe products in a common way according to industry best practices. After configuration is complete, you can execute the product and easily provision new software instances for use on other systems throughout your environment. -## End-to-end installation diagram +## End-to-end installation diagram ![PSWI installation diagram](../images/install/PSWI-install.png) @@ -19,19 +19,20 @@ To install Zowe using z/OSMF, ensure that you meet the following requirements: Refer to the following subpages to guide you through the installation procedure using z/OSMF. -* [Address z/OSMF Requirements](./install-zowe-pswi-address-requirements.md) +- [Address z/OSMF Requirements](./install-zowe-pswi-address-requirements.md) Provides information about z/OSMF general configuration and security requirements. -* [Acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire.md) +- [Acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire.md) Provides the steps to acquire the product software by downloading the z/OSMF portable software instance to the z/OSMF host. You must then register the portable software instance in z/OSMF. -* [Install Product Software Using z/OSMF Deployments](./install-zowe-pswi-deployment.md) +- [Install Product Software Using z/OSMF Deployments](./install-zowe-pswi-deployment.md) Provides the steps to install (deploy) the portable software instance to an LPAR using z/OSMF Deployments. This step creates the SMP/E environment and runs the RECEIVE, APPLY, and ACCEPT steps to prepare the software instance for SMP/E operations. This step also: - * Customizes the data set names that are defined to SMP/E. - * Mounts required USS files if necessary. - * Performs workflow execution to customize the deployed runtime environment for use on a specific z/OS system. + +- Customizes the data set names that are defined to SMP/E. +- Mounts required USS files if necessary. +- Performs workflow execution to customize the deployed runtime environment for use on a specific z/OS system. When these tasks are completed, you are ready to install preventive maintenance. From 7e2fba3e7d7bf51c4b87708b12d201b928b5b0c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Wed, 27 Nov 2024 14:14:03 +0100 Subject: [PATCH 51/67] add recommendations for installation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- docs/user-guide/install-zowe-pswi-acquire.md | 2 +- .../install-zowe-pswi-deployment.md | 36 +++++++++++++++--- .../user-guide/install-zowe-pswi-acquire.md | 2 +- .../install-zowe-pswi-deployment.md | 38 ++++++++++++++++--- 4 files changed, 65 insertions(+), 13 deletions(-) diff --git a/docs/user-guide/install-zowe-pswi-acquire.md b/docs/user-guide/install-zowe-pswi-acquire.md index ad47470f65..87090b9c6e 100644 --- a/docs/user-guide/install-zowe-pswi-acquire.md +++ b/docs/user-guide/install-zowe-pswi-acquire.md @@ -38,7 +38,7 @@ To acquire the portable software instance, you can download it from the Zowe Dow 2. Update the USS directory (*yourUSSpaxdirectory*) with the path name where you want to copy the pax file. 3. Update *yourpaxfilename* with the name of the pax file that you want to copy to the mainframe. -:::tip Expected results: +:::tip Expected results: USSBATCH can take several minutes to execute. You will receive a return code of 0 if this job runs correctly. ::: diff --git a/docs/user-guide/install-zowe-pswi-deployment.md b/docs/user-guide/install-zowe-pswi-deployment.md index e751605e59..d1dcf0ba8f 100644 --- a/docs/user-guide/install-zowe-pswi-deployment.md +++ b/docs/user-guide/install-zowe-pswi-deployment.md @@ -5,7 +5,7 @@ After the portable software instance or software instance is registered in z/OSMF, you can use z/OSMF Deployments to install the product software and create the product data sets (global, CSI, target libraries, and distribution libraries) for the new software instance. The deployment jobs create a copy of the source product data sets to create the product target runtime environment. Creating a copy of the SMP/E target data sets keeps the SMP/E environment clean and separates the product runtime environment for maintenance activities. You can also perform z/OSMF workflows to customize the SMP/E data sets, mount UNIX System Services (USS) files if necessary, and configure the new software instance on the target system. -To install Zowe PSWI using z/OSMF and make the product software available for use on a system by users and other programs, you need to define a new deployment. This step defines the SMP/E environment name and the prefix of the CSI data set in z/OSMF. Specify data set allocation parameters for all SMP/E data sets, target libraries, and distribution libraries. +To install Zowe PSWI using z/OSMF and make the product software available for use on a system by users and other programs, you need to define a new deployment. This step defines the SMP/E environment name and the prefix of the CSI data set in z/OSMF. Specify data set allocation parameters for all SMP/E data sets, target libraries, and distribution libraries. To define a new deployment, complete the deployment checklist (specify the USS path, DSN, VOLSERs), and submit the deployment jobs through the z/OSMF user interface. When the deployment is complete, you have a source and target copy of the software. @@ -41,20 +41,21 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re **Example:** `_targetpathname_**/staticpathextension**`. **Note:** If your product does not include USS directories, ignore this instruction. - 6. Define the job settings to generate the JCL to install the software and view the deployment summary. Update the JOB statement as needed. - **Note:** If the target system for the deployment is in a JES Multi-Access Spool (MAS) and the mount point is only accessible from the target system, add a System Affinity (SYSAFF) to the job card to ensure execution on the system where the zFS resides. + 6. Define the job settings to generate the JCL to install the software and view the deployment summary. Update the JOB statement as needed. + + **Note:** If the target system for the deployment is in a JES Multi-Access Spool (MAS) and the mount point is only accessible from the target system, add a System Affinity (SYSAFF) to the job card to ensure execution on the system where the zFS resides. 7. Submit the deployment jobs in sequential order, wait for each job to complete, and then select **Refresh** to register job completion in z/OSMF. :::tip Expected results: You will receive a return code of 0 if this job runs correctly. When all deployment jobs are executed successfully, you have unzipped, renamed and copied the product data sets, updated the CSI data set, and specified the properties for the target software instance. ::: - + 8. Complete **Mount Workflow** to mount the Zowe zFS. Complete both steps in the workflow. Perform the following steps to execute each step individually: 1. Click the title of the step. 2. Select the Perform tab. 3. Review the step contents and update the JCL if needed. 4. Select Next. - 5. Repeat the previous two steps to complete all items until the Finish option is available. + 5. Repeat the previous two steps to complete all items until the Finish option is available. 9. (Optional) To configure your Zowe instance, follow the procedure in [Configuring Zowe with z/OSMF Workflows](configure-zowe-zosmf-workflow.md). @@ -64,3 +65,28 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re **Note:** You do not have to execute all workflows during PSWI provisioning in z/OSMF immediately. The deployment process is complete. The new software instance is defined to z/OSMF. You are now ready to Import Product Information into z/OSMF before you install product maintenance. + +## Recommendations + +### Cleanup + +If the job execution fails, the deployment process does not perform a full cleanup of the datasets, before attempting it again, make sure the following datasets are deleted: + +```plaintext +{TARGET_HLQ}.D.AZWEAUTH.# +{TARGET_HLQ}.D.AZWEZFS.# +{TARGET_HLQ}.SMPLOG.# +{TARGET_HLQ}.SMPLOGA.# +{TARGET_HLQ}.SMPLTS.# +{TARGET_HLQ}.SMPMTS.# +{TARGET_HLQ}.SMPSCDS.# +{TARGET_HLQ}.T.SZWEAUTH.# +{TARGET_HLQ}.T.SZWEEXEC.# +{TARGET_HLQ}.T.SZWELOAD.# + +{TARGET_HLQ}.CSI.# +``` + +### Resources + +It is recommended to update the job card to run with `REGION=0M`, particularly for job `IZUD01DZ` which unpaxes the contents. diff --git a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-acquire.md b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-acquire.md index ad47470f65..87090b9c6e 100644 --- a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-acquire.md +++ b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-acquire.md @@ -38,7 +38,7 @@ To acquire the portable software instance, you can download it from the Zowe Dow 2. Update the USS directory (*yourUSSpaxdirectory*) with the path name where you want to copy the pax file. 3. Update *yourpaxfilename* with the name of the pax file that you want to copy to the mainframe. -:::tip Expected results: +:::tip Expected results: USSBATCH can take several minutes to execute. You will receive a return code of 0 if this job runs correctly. ::: diff --git a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md index 866723aee8..d1dcf0ba8f 100644 --- a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md +++ b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md @@ -5,7 +5,7 @@ After the portable software instance or software instance is registered in z/OSMF, you can use z/OSMF Deployments to install the product software and create the product data sets (global, CSI, target libraries, and distribution libraries) for the new software instance. The deployment jobs create a copy of the source product data sets to create the product target runtime environment. Creating a copy of the SMP/E target data sets keeps the SMP/E environment clean and separates the product runtime environment for maintenance activities. You can also perform z/OSMF workflows to customize the SMP/E data sets, mount UNIX System Services (USS) files if necessary, and configure the new software instance on the target system. -To install Zowe PSWI using z/OSMF and make the product software available for use on a system by users and other programs, you need to define a new deployment. This step defines the SMP/E environment name and the prefix of the CSI data set in z/OSMF. Specify data set allocation parameters for all SMP/E data sets, target libraries, and distribution libraries. +To install Zowe PSWI using z/OSMF and make the product software available for use on a system by users and other programs, you need to define a new deployment. This step defines the SMP/E environment name and the prefix of the CSI data set in z/OSMF. Specify data set allocation parameters for all SMP/E data sets, target libraries, and distribution libraries. To define a new deployment, complete the deployment checklist (specify the USS path, DSN, VOLSERs), and submit the deployment jobs through the z/OSMF user interface. When the deployment is complete, you have a source and target copy of the software. @@ -41,20 +41,21 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re **Example:** `_targetpathname_**/staticpathextension**`. **Note:** If your product does not include USS directories, ignore this instruction. - 6. Define the job settings to generate the JCL to install the software and view the deployment summary. Update the JOB statement as needed. - **Note:** If the target system for the deployment is in a JES Multi-Access Spool (MAS) and the mount point is only accessible from the target system, add a System Affinity (SYSAFF) to the job card to ensure execution on the system where the zFS resides. + 6. Define the job settings to generate the JCL to install the software and view the deployment summary. Update the JOB statement as needed. + + **Note:** If the target system for the deployment is in a JES Multi-Access Spool (MAS) and the mount point is only accessible from the target system, add a System Affinity (SYSAFF) to the job card to ensure execution on the system where the zFS resides. 7. Submit the deployment jobs in sequential order, wait for each job to complete, and then select **Refresh** to register job completion in z/OSMF. - :::tip Expected results: + :::tip Expected results: You will receive a return code of 0 if this job runs correctly. When all deployment jobs are executed successfully, you have unzipped, renamed and copied the product data sets, updated the CSI data set, and specified the properties for the target software instance. ::: - + 8. Complete **Mount Workflow** to mount the Zowe zFS. Complete both steps in the workflow. Perform the following steps to execute each step individually: 1. Click the title of the step. 2. Select the Perform tab. 3. Review the step contents and update the JCL if needed. 4. Select Next. - 5. Repeat the previous two steps to complete all items until the Finish option is available. + 5. Repeat the previous two steps to complete all items until the Finish option is available. 9. (Optional) To configure your Zowe instance, follow the procedure in [Configuring Zowe with z/OSMF Workflows](configure-zowe-zosmf-workflow.md). @@ -64,3 +65,28 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re **Note:** You do not have to execute all workflows during PSWI provisioning in z/OSMF immediately. The deployment process is complete. The new software instance is defined to z/OSMF. You are now ready to Import Product Information into z/OSMF before you install product maintenance. + +## Recommendations + +### Cleanup + +If the job execution fails, the deployment process does not perform a full cleanup of the datasets, before attempting it again, make sure the following datasets are deleted: + +```plaintext +{TARGET_HLQ}.D.AZWEAUTH.# +{TARGET_HLQ}.D.AZWEZFS.# +{TARGET_HLQ}.SMPLOG.# +{TARGET_HLQ}.SMPLOGA.# +{TARGET_HLQ}.SMPLTS.# +{TARGET_HLQ}.SMPMTS.# +{TARGET_HLQ}.SMPSCDS.# +{TARGET_HLQ}.T.SZWEAUTH.# +{TARGET_HLQ}.T.SZWEEXEC.# +{TARGET_HLQ}.T.SZWELOAD.# + +{TARGET_HLQ}.CSI.# +``` + +### Resources + +It is recommended to update the job card to run with `REGION=0M`, particularly for job `IZUD01DZ` which unpaxes the contents. From 49e5ae49a505c9c258a398c2a728bafbd6c85efb Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 27 Nov 2024 17:13:39 +0100 Subject: [PATCH 52/67] language/grammar improvements Signed-off-by: Andrew Jandacek --- docs/user-guide/install-zowe-pswi-acquire.md | 26 +++++++++++-------- .../install-zowe-pswi-deployment.md | 15 ++++++----- 2 files changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/user-guide/install-zowe-pswi-acquire.md b/docs/user-guide/install-zowe-pswi-acquire.md index 87090b9c6e..d21e037025 100644 --- a/docs/user-guide/install-zowe-pswi-acquire.md +++ b/docs/user-guide/install-zowe-pswi-acquire.md @@ -4,23 +4,27 @@ As a systems programmer, you can acquire an IBM z/OSMF portable package for your When you complete the acquisition process, the product software is ready for installation using z/OSMF Deployments. -- **Note**: Before you begin the acquisition process, ensure that you address the z/OSMF requirements. +:::note +Before you begin the acquisition process, ensure that you address the z/OSMF requirements. +::: The z/OSMF product acquisition process consists of 2 tasks. -1. Download the portable software instance from Zowe downloads and transfer it to the mainframe. +1. Download the portable software instance from Zowe downloads and transfer the instance to the mainframe. 2. Register the portable software instance in z/OSMF. ## Download the Portable Software Instance from Zowe Downloads The portable software instance is a portable form of a software instance, including the SMP/E CSI data sets, all associated SMP/E-managed target and distribution libraries, non-SMP/E-managed data sets, and meta-data that is required to describe the product software instance. -To acquire the portable software instance, you can download it from the Zowe Downloads page and transfer it to a local z/OSMF host using a file transfer utility, such as FTP. +To acquire the portable software instance, you can download it from the Zowe Downloads page and transfer the instance to a local z/OSMF host using a file transfer utility, such as FTP. 1. Go to [Zowe Downloads](https://www.zowe.org/download.html) and find **Zowe - Portable Software Instance**. 2. Download the latest version of the package to your workstation. -3. Use an file transfer utility such as an FTP client to transfer the single pax file to the mainframe. -4. Execute the JCL to unpack the installation file and restore the individual pax files. Sample JCL follows: +3. Use a file transfer utility such as an FTP client to transfer the single pax file to the mainframe. +4. Execute the JCL to unpack the installation file and restore the individual pax files. + +**Sample JCL:** ```jcl //USSBATCH EXEC PGM=BPXBATCH @@ -32,30 +36,30 @@ To acquire the portable software instance, you can download it from the Zowe Dow /* ``` -1. Customize the sample JCL as follows and then submit for execution: +5. Customize the sample JCL as follows and then submit for execution: 1. Add a JOB statement. 2. Update the USS directory (*yourUSSpaxdirectory*) with the path name where you want to copy the pax file. 3. Update *yourpaxfilename* with the name of the pax file that you want to copy to the mainframe. :::tip Expected results: -USSBATCH can take several minutes to execute. You will receive a return code of 0 if this job runs correctly. +USSBATCH can take several minutes to execute. You will receive a return code of `0` if this job runs correctly. ::: -After successful execution, the individual pax files are restored and ready for use. Next step is to Register Portable Software Instance in z/OSMF. +After successful execution, the individual pax files are restored and ready for use. The next step is to register the Portable Software Instance in z/OSMF. ## Register Portable Software Instance in z/OSMF -After you have acquired and downloaded the portable software instance to a local z/OSMF host system, you must log in to z/OSMF to register the product software and define the portable software instance to z/OSMF as shown in the following procedure. When you complete these steps, the portable software instance is registered in z/OSMF and ready for installation (deployment). +After you have acquired and downloaded the portable software instance to a local z/OSMF host system, it is necessary to log in to z/OSMF to register the product software and define the portable software instance to z/OSMF as shown in the following procedure. When you complete these steps, the portable software instance is registered in z/OSMF and ready for installation (deployment). 1. Log in to the z/OSMF web interface and select your user ID in the top or bottom right-hand corner to switch between the Desktop Interface and Classic Interface. 2. Complete **either** of the following steps to display the Software Management page: 1. In the Desktop Interface, select **Software Management**. 2. In the Classic Interface, select **Software**, **Software Management**. 3. Select **Portable Software Instances** to define your portable software instance to z/OSMF. -4. Select **Add** from the Actions menu and select **From z/OSMF System**. Then the Add Portable Software Instance page should display. +4. Select **Add** from the Actions menu and select **From z/OSMF System**. The _Add Portable Software Instance_ page should display. 5. Select or type the system name (destination LPAR) and UNIX directory (destination USS directory) where the portable software instance files reside and select **Retrieve**. 6. Enter a name for the new portable software instance. You can also enter an optional description and assign one or more categories that display existing packages. 7. Select **OK**. -Now the new portable software instance is defined to z/OSMF. And the portable software instance is now registered in z/OSMF and ready to install (deploy). +The new portable software instance is now defined to z/OSMF, and the portable software instance is registered in z/OSMF and ready to install (deploy). diff --git a/docs/user-guide/install-zowe-pswi-deployment.md b/docs/user-guide/install-zowe-pswi-deployment.md index d1dcf0ba8f..643bea6ac8 100644 --- a/docs/user-guide/install-zowe-pswi-deployment.md +++ b/docs/user-guide/install-zowe-pswi-deployment.md @@ -18,7 +18,7 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re ## Installing process 1. Display the Deployments table in z/OSMF (**Software ManagementU**, **Deployments**). -2. Define a new deployment by selecting **New** from the Actions menu. The deployment checklist displays, where you can also modify, view, copy, cancel, or remove existing deployments. +2. Define a new deployment by selecting **New** from the Actions menu. The deployment checklist displays where you can also modify, view, copy, cancel, or remove existing deployments. 3. Complete the deployment checklist items as described in _Defining new deployments_ in the IBM documentation. As you complete the deployment checklist, be sure to make the following selections: 1. Specify the properties for this deployment (name, description, and optional category). @@ -45,17 +45,18 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re **Note:** If the target system for the deployment is in a JES Multi-Access Spool (MAS) and the mount point is only accessible from the target system, add a System Affinity (SYSAFF) to the job card to ensure execution on the system where the zFS resides. - 7. Submit the deployment jobs in sequential order, wait for each job to complete, and then select **Refresh** to register job completion in z/OSMF. + 7. Submit the deployment jobs in sequential order. Wait for each job to complete, and then select **Refresh** to register job completion in z/OSMF. + :::tip Expected results: - You will receive a return code of 0 if this job runs correctly. When all deployment jobs are executed successfully, you have unzipped, renamed and copied the product data sets, updated the CSI data set, and specified the properties for the target software instance. + You will receive a return code of `0` if this job runs correctly. When all deployment jobs are executed successfully, you have unzipped, renamed and copied the product data sets, updated the CSI data set, and specified the properties for the target software instance. ::: 8. Complete **Mount Workflow** to mount the Zowe zFS. Complete both steps in the workflow. Perform the following steps to execute each step individually: 1. Click the title of the step. - 2. Select the Perform tab. + 2. Select the **Perform** tab. 3. Review the step contents and update the JCL if needed. - 4. Select Next. - 5. Repeat the previous two steps to complete all items until the Finish option is available. + 4. Select **Next**. + 5. Repeat the previous two steps to complete all items until the **Finish** option is available. 9. (Optional) To configure your Zowe instance, follow the procedure in [Configuring Zowe with z/OSMF Workflows](configure-zowe-zosmf-workflow.md). @@ -70,7 +71,7 @@ The deployment process is complete. The new software instance is defined to z/OS ### Cleanup -If the job execution fails, the deployment process does not perform a full cleanup of the datasets, before attempting it again, make sure the following datasets are deleted: +If the job execution fails, the deployment process does not perform a full cleanup of the datasets. Before attempting job execution again, make sure the following datasets are deleted: ```plaintext {TARGET_HLQ}.D.AZWEAUTH.# From 01766a0bab1b85dd2f6b888606612ca83c052009 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 27 Nov 2024 17:39:01 +0100 Subject: [PATCH 53/67] minor language/formatting refactor for v2.18 Signed-off-by: Andrew Jandacek --- .../user-guide/install-zowe-pswi-acquire.md | 24 +++++++++++-------- .../install-zowe-pswi-deployment.md | 15 ++++++------ 2 files changed, 22 insertions(+), 17 deletions(-) diff --git a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-acquire.md b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-acquire.md index 87090b9c6e..e477b38278 100644 --- a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-acquire.md +++ b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-acquire.md @@ -4,23 +4,27 @@ As a systems programmer, you can acquire an IBM z/OSMF portable package for your When you complete the acquisition process, the product software is ready for installation using z/OSMF Deployments. -- **Note**: Before you begin the acquisition process, ensure that you address the z/OSMF requirements. +:::note +Before you begin the acquisition process, ensure that you address the z/OSMF requirements. +::: The z/OSMF product acquisition process consists of 2 tasks. -1. Download the portable software instance from Zowe downloads and transfer it to the mainframe. +1. Download the portable software instance from Zowe downloads and transfer the instance to the mainframe. 2. Register the portable software instance in z/OSMF. ## Download the Portable Software Instance from Zowe Downloads The portable software instance is a portable form of a software instance, including the SMP/E CSI data sets, all associated SMP/E-managed target and distribution libraries, non-SMP/E-managed data sets, and meta-data that is required to describe the product software instance. -To acquire the portable software instance, you can download it from the Zowe Downloads page and transfer it to a local z/OSMF host using a file transfer utility, such as FTP. +To acquire the portable software instance, you can download it from the Zowe Downloads page and transfer the instance to a local z/OSMF host using a file transfer utility, such as FTP. 1. Go to [Zowe Downloads](https://www.zowe.org/download.html) and find **Zowe - Portable Software Instance**. 2. Download the latest version of the package to your workstation. 3. Use an file transfer utility such as an FTP client to transfer the single pax file to the mainframe. -4. Execute the JCL to unpack the installation file and restore the individual pax files. Sample JCL follows: +4. Execute the JCL to unpack the installation file and restore the individual pax files. + +**Sample JCL:** ```jcl //USSBATCH EXEC PGM=BPXBATCH @@ -32,30 +36,30 @@ To acquire the portable software instance, you can download it from the Zowe Dow /* ``` -1. Customize the sample JCL as follows and then submit for execution: +5. Customize the sample JCL as follows and then submit for execution: 1. Add a JOB statement. 2. Update the USS directory (*yourUSSpaxdirectory*) with the path name where you want to copy the pax file. 3. Update *yourpaxfilename* with the name of the pax file that you want to copy to the mainframe. :::tip Expected results: -USSBATCH can take several minutes to execute. You will receive a return code of 0 if this job runs correctly. +USSBATCH can take several minutes to execute. You will receive a return code of `0` if this job runs correctly. ::: -After successful execution, the individual pax files are restored and ready for use. Next step is to Register Portable Software Instance in z/OSMF. +After successful execution, the individual pax files are restored and ready for use. The next step is to register the Portable Software Instance in z/OSMF. ## Register Portable Software Instance in z/OSMF -After you have acquired and downloaded the portable software instance to a local z/OSMF host system, you must log in to z/OSMF to register the product software and define the portable software instance to z/OSMF as shown in the following procedure. When you complete these steps, the portable software instance is registered in z/OSMF and ready for installation (deployment). +After you have acquired and downloaded the portable software instance to a local z/OSMF host system, it is necessary to log in to z/OSMF to register the product software and define the portable software instance to z/OSMF as shown in the following procedure. When you complete these steps, the portable software instance is registered in z/OSMF and ready for installation (deployment). 1. Log in to the z/OSMF web interface and select your user ID in the top or bottom right-hand corner to switch between the Desktop Interface and Classic Interface. 2. Complete **either** of the following steps to display the Software Management page: 1. In the Desktop Interface, select **Software Management**. 2. In the Classic Interface, select **Software**, **Software Management**. 3. Select **Portable Software Instances** to define your portable software instance to z/OSMF. -4. Select **Add** from the Actions menu and select **From z/OSMF System**. Then the Add Portable Software Instance page should display. +4. Select **Add** from the Actions menu and select **From z/OSMF System**. The _Add Portable Software Instance_ page should display. 5. Select or type the system name (destination LPAR) and UNIX directory (destination USS directory) where the portable software instance files reside and select **Retrieve**. 6. Enter a name for the new portable software instance. You can also enter an optional description and assign one or more categories that display existing packages. 7. Select **OK**. -Now the new portable software instance is defined to z/OSMF. And the portable software instance is now registered in z/OSMF and ready to install (deploy). +The new portable software instance is now defined to z/OSMF. The portable software instance is registered in z/OSMF and ready to install (deploy). diff --git a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md index d1dcf0ba8f..e55e558308 100644 --- a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md +++ b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md @@ -18,7 +18,7 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re ## Installing process 1. Display the Deployments table in z/OSMF (**Software ManagementU**, **Deployments**). -2. Define a new deployment by selecting **New** from the Actions menu. The deployment checklist displays, where you can also modify, view, copy, cancel, or remove existing deployments. +2. Define a new deployment by selecting **New** from the Actions menu. The deployment checklist displays where you can also modify, view, copy, cancel, or remove existing deployments. 3. Complete the deployment checklist items as described in _Defining new deployments_ in the IBM documentation. As you complete the deployment checklist, be sure to make the following selections: 1. Specify the properties for this deployment (name, description, and optional category). @@ -45,17 +45,18 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re **Note:** If the target system for the deployment is in a JES Multi-Access Spool (MAS) and the mount point is only accessible from the target system, add a System Affinity (SYSAFF) to the job card to ensure execution on the system where the zFS resides. - 7. Submit the deployment jobs in sequential order, wait for each job to complete, and then select **Refresh** to register job completion in z/OSMF. + 7. Submit the deployment jobs in sequential order, wait for each job to complete, and then select **Refresh** to register job completion in z/OSMF. + :::tip Expected results: - You will receive a return code of 0 if this job runs correctly. When all deployment jobs are executed successfully, you have unzipped, renamed and copied the product data sets, updated the CSI data set, and specified the properties for the target software instance. + You will receive a return code of `0` if this job runs correctly. When all deployment jobs are executed successfully, you have unzipped, renamed and copied the product data sets, updated the CSI data set, and specified the properties for the target software instance. ::: 8. Complete **Mount Workflow** to mount the Zowe zFS. Complete both steps in the workflow. Perform the following steps to execute each step individually: 1. Click the title of the step. - 2. Select the Perform tab. + 2. Select the **Perform** tab. 3. Review the step contents and update the JCL if needed. - 4. Select Next. - 5. Repeat the previous two steps to complete all items until the Finish option is available. + 4. Select **Next**. + 5. Repeat the previous two steps to complete all items until the **Finish** option is available. 9. (Optional) To configure your Zowe instance, follow the procedure in [Configuring Zowe with z/OSMF Workflows](configure-zowe-zosmf-workflow.md). @@ -70,7 +71,7 @@ The deployment process is complete. The new software instance is defined to z/OS ### Cleanup -If the job execution fails, the deployment process does not perform a full cleanup of the datasets, before attempting it again, make sure the following datasets are deleted: +If the job execution fails, the deployment process does not perform a full cleanup of the datasets, before attempting job execution again, make sure the following datasets are deleted: ```plaintext {TARGET_HLQ}.D.AZWEAUTH.# From 18c57fd04f91d023f2e78b2fc8f15eaa1b61ea48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Thu, 28 Nov 2024 09:50:54 +0100 Subject: [PATCH 54/67] sysplex and first pr review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- docs/user-guide/configure-sysplex.md | 5 ++--- docs/user-guide/install-zowe-pswi-acquire.md | 22 +++++++++---------- .../user-guide/configure-sysplex.md | 6 ++--- 3 files changed, 16 insertions(+), 17 deletions(-) diff --git a/docs/user-guide/configure-sysplex.md b/docs/user-guide/configure-sysplex.md index fe5fed7e06..c14dffe362 100644 --- a/docs/user-guide/configure-sysplex.md +++ b/docs/user-guide/configure-sysplex.md @@ -31,7 +31,7 @@ The following example DVIPA configuration ensures the availability of Zowe in Ho 2. Define a DVIPA for both systems: - ``` + ```plaintext VIPADYNAMIC VIPADEFINE 255.255.255.0 x.x.x.V VIPADISTRIBUTE DEFINE DISTM HOTSTANDBY x.x.x.V @@ -61,7 +61,7 @@ If SYSA fails, new work requests to Zowe are routed to the server on SYSB. When 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. -``` +```plaintext VIPADYNAMIC VIPADEFINE 255.255.255.0 x.x.x.V VIPADISTRIBUTE DEFINE DISTM HOTSTANDBY NOAUTOSWITCHBACK x.x.x.V @@ -70,4 +70,3 @@ VIPADYNAMIC x.x.x.B BACKUP ENDVIPADYNAMIC ``` - diff --git a/docs/user-guide/install-zowe-pswi-acquire.md b/docs/user-guide/install-zowe-pswi-acquire.md index 87090b9c6e..0cde4d6b56 100644 --- a/docs/user-guide/install-zowe-pswi-acquire.md +++ b/docs/user-guide/install-zowe-pswi-acquire.md @@ -22,17 +22,17 @@ To acquire the portable software instance, you can download it from the Zowe Dow 3. Use an file transfer utility such as an FTP client to transfer the single pax file to the mainframe. 4. Execute the JCL to unpack the installation file and restore the individual pax files. Sample JCL follows: -```jcl - //USSBATCH EXEC PGM=BPXBATCH - //STDOUT DD SYSOUT=* - //STDERR DD SYSOUT=* - //STDPARM DD * - sh cd /yourUSSpaxdirectory/; - pax -rvf yourpaxfilename.ZOSMF.pax.Z - /* -``` - -1. Customize the sample JCL as follows and then submit for execution: + ```jcl + //USSBATCH EXEC PGM=BPXBATCH + //STDOUT DD SYSOUT=* + //STDERR DD SYSOUT=* + //STDPARM DD * + sh cd /yourUSSpaxdirectory/; + pax -rvf yourpaxfilename.ZOSMF.pax.Z + /* + ``` + +5. Customize the sample JCL as follows and then submit for execution: 1. Add a JOB statement. 2. Update the USS directory (*yourUSSpaxdirectory*) with the path name where you want to copy the pax file. diff --git a/versioned_docs/version-v2.18.x/user-guide/configure-sysplex.md b/versioned_docs/version-v2.18.x/user-guide/configure-sysplex.md index 4cd8cafc55..d78713b14c 100644 --- a/versioned_docs/version-v2.18.x/user-guide/configure-sysplex.md +++ b/versioned_docs/version-v2.18.x/user-guide/configure-sysplex.md @@ -13,6 +13,7 @@ Zowe high availability instances require a Sysplex environment that consists of - 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) + - Not required if using infinispan as Caching Service solution. VSAM storage for the Caching Service is deprecated and will be removed in a future release. - 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) @@ -32,7 +33,7 @@ The following example DVIPA configuration ensures the availability of Zowe in Ho 2. Define a DVIPA for both systems: - ``` + ```plaintext VIPADYNAMIC VIPADEFINE 255.255.255.0 x.x.x.V VIPADISTRIBUTE DEFINE DISTM HOTSTANDBY x.x.x.V @@ -62,7 +63,7 @@ If SYSA fails, new work requests to Zowe are routed to the server on SYSB. When 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. -``` +```plaintext VIPADYNAMIC VIPADEFINE 255.255.255.0 x.x.x.V VIPADISTRIBUTE DEFINE DISTM HOTSTANDBY NOAUTOSWITCHBACK x.x.x.V @@ -71,4 +72,3 @@ VIPADYNAMIC x.x.x.B BACKUP ENDVIPADYNAMIC ``` - From b119d823c15eb40d9a3fd4fedc8afd238545515a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Thu, 28 Nov 2024 10:04:27 +0100 Subject: [PATCH 55/67] address review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../install-zowe-pswi-deployment.md | 40 +++++++++++-------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/docs/user-guide/install-zowe-pswi-deployment.md b/docs/user-guide/install-zowe-pswi-deployment.md index 643bea6ac8..b854c0a46b 100644 --- a/docs/user-guide/install-zowe-pswi-deployment.md +++ b/docs/user-guide/install-zowe-pswi-deployment.md @@ -47,9 +47,9 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re 7. Submit the deployment jobs in sequential order. Wait for each job to complete, and then select **Refresh** to register job completion in z/OSMF. - :::tip Expected results: - You will receive a return code of `0` if this job runs correctly. When all deployment jobs are executed successfully, you have unzipped, renamed and copied the product data sets, updated the CSI data set, and specified the properties for the target software instance. - ::: + :::tip Expected results: + You will receive a return code of `0` if this job runs correctly. When all deployment jobs are executed successfully, you have unzipped, renamed and copied the product data sets, updated the CSI data set, and specified the properties for the target software instance. + ::: 8. Complete **Mount Workflow** to mount the Zowe zFS. Complete both steps in the workflow. Perform the following steps to execute each step individually: 1. Click the title of the step. @@ -71,23 +71,31 @@ The deployment process is complete. The new software instance is defined to z/OS ### Cleanup -If the job execution fails, the deployment process does not perform a full cleanup of the datasets. Before attempting job execution again, make sure the following datasets are deleted: +If there is a need to update the deployment settings such as the HLQ after a previour run, consider that the deployment process does not perform a full cleanup of the datasets. +Before attempting it again, make sure the following datasets are deleted to avoid write conflicts: ```plaintext -{TARGET_HLQ}.D.AZWEAUTH.# -{TARGET_HLQ}.D.AZWEZFS.# -{TARGET_HLQ}.SMPLOG.# -{TARGET_HLQ}.SMPLOGA.# -{TARGET_HLQ}.SMPLTS.# -{TARGET_HLQ}.SMPMTS.# -{TARGET_HLQ}.SMPSCDS.# -{TARGET_HLQ}.T.SZWEAUTH.# -{TARGET_HLQ}.T.SZWEEXEC.# -{TARGET_HLQ}.T.SZWELOAD.# - -{TARGET_HLQ}.CSI.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.CSI +{TARGET_HLQ}.PRODUCT.ZOWE.V2.D.AZWEAUTH.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.D.AZWESAMP.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.D.AZWEZFS.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPLOG.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPLOGA.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPLTS.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPMTS.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPPTS.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPSCDS.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPSTS.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.T.SZWEAUTH.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.T.SZWEEXEC.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.T.SZWELOAD.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.T.SZWESAMP.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.WORKFLOW.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.ZFS.# ``` +If deployment options must be modified and the JCL recreated, before doing so, check the original JCL for the temporary ZFS dataset name like `.SWDEPL..ZFS` and delete it manually. The deployment job will be unable to clean it once it is recreated because the random id will change. + ### Resources It is recommended to update the job card to run with `REGION=0M`, particularly for job `IZUD01DZ` which unpaxes the contents. From a4e0489b359b216956c2b89994bb26a70b23d870 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 28 Nov 2024 11:17:09 +0100 Subject: [PATCH 56/67] add troubleshooting entry Signed-off-by: Andrew Jandacek --- .../troubleshoot-zos-certificate.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/versioned_docs/version-v2.18.x/troubleshoot/troubleshoot-zos-certificate.md b/versioned_docs/version-v2.18.x/troubleshoot/troubleshoot-zos-certificate.md index 2ba1a9a87f..b4b5a72f4a 100644 --- a/versioned_docs/version-v2.18.x/troubleshoot/troubleshoot-zos-certificate.md +++ b/versioned_docs/version-v2.18.x/troubleshoot/troubleshoot-zos-certificate.md @@ -369,3 +369,43 @@ security.provider.13=JdkSASL security.provider.14=SunPKCS11 ``` For more information see the steps in [Enabling the IBMZSecurity provider](https://www.ibm.com/docs/en/semeru-runtime-ce-z/11?topic=guide-ibmzsecurity#ibmzsecurity__enabling_z_provider__title__1). + + +## Third-party certificate managemenrt tools may require additional steps for Zowe functionality + +**Symptom:** + +If using a third-party tool to generate a self-signed intermediate certificate for Zowe, it is possible that Zowe will not be functional. + +**Solution:** + +You can try to troubleshoot this issue by taking the following addtional steps during configuration: + +1. Note the specific root certificate with which the generated intermediate certificate was self-signed. + +2. Ask your Security Administrator to perfrom the following tasks: + + * Add the generated intermediate certificate to Zowe's Keyring. + * Add the root certificate to Zowe's Keyring. + * Once the keyring has been configured, add the root certificate in the Default Zowe certificate section under `pem.certificateAuthorities`. + + **Note:** Since the Default Zowe certificate section can have at most two entries, ensure that the entires are listed in the following order: + + * The first entry should be your generated intermediate certificate authority. + * The second and final entry should be the root certificate authority. + + Failure to add the root certificate in this sequence, prevents the user from setting `verifyCertificates` to `STRICT`. + + **Example:** + ``` + pem: + # key: /global/zowe/keystore/localhost/localhost.key + # certificate: /global/zowe/keystore/localhost/localhost.cer + # if keyrings, the format is "safkeyring:////stcusername/KeyName&ca name" + key: + certificate: + certificateAuthorities: + - "safkeyring:////ZWESVUSR/ZWEKEYRING.ZWEDFLT&CERTAUTH.AJMCA1" + - "safkeyring:////ZWESVUSR/ZWEKEYRING.ZWEDFLT&CERTAUTH.AJMROOT" + ``` + From 33b9e8caa21053263a2f0fef6fff0d5a5f815883 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 28 Nov 2024 11:18:47 +0100 Subject: [PATCH 57/67] add new tip to TOC Signed-off-by: Andrew Jandacek --- .../version-v2.18.x/troubleshoot/troubleshoot-zos-certificate.md | 1 + 1 file changed, 1 insertion(+) diff --git a/versioned_docs/version-v2.18.x/troubleshoot/troubleshoot-zos-certificate.md b/versioned_docs/version-v2.18.x/troubleshoot/troubleshoot-zos-certificate.md index b4b5a72f4a..64fe3ff056 100644 --- a/versioned_docs/version-v2.18.x/troubleshoot/troubleshoot-zos-certificate.md +++ b/versioned_docs/version-v2.18.x/troubleshoot/troubleshoot-zos-certificate.md @@ -13,6 +13,7 @@ As an API Mediation Layer user, you may encounter problems when configuring cert * [Exception thrown when reading SAF keyring \{ZWED0148E\}](#exception-thrown-when-reading-saf-keyring-zwed0148e) * [ZWEAM400E Error initializing SSL Context when using Java 11](#zweam400e-error-initializing-ssl-context-when-using-java-11) * [Failed to load JCERACFKS keyring when using Java 11](#failed-to-load-jceracfks-keyring-when-using-java-11) +* [Third-party certificate managemenrt tools may require additional steps for Zowe functionality](#third-party-certificate-managemenrt-tools-may-require-additional-steps-for-zowe-functionality) ## PKCS12 server keystore generation fails in Java 8 SR7FP15, SR7 FP16, and SR7 FP20 From b3f3d17d31ad65c8b1af019384cbe42bea53c9fa Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Tue, 3 Dec 2024 12:23:02 +0100 Subject: [PATCH 58/67] add notes/improve section formatting Signed-off-by: Andrew Jandacek --- .../install-zowe-pswi-deployment.md | 32 +++++++++++++++---- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/user-guide/install-zowe-pswi-deployment.md b/docs/user-guide/install-zowe-pswi-deployment.md index b854c0a46b..2a3ce71e5e 100644 --- a/docs/user-guide/install-zowe-pswi-deployment.md +++ b/docs/user-guide/install-zowe-pswi-deployment.md @@ -5,11 +5,18 @@ After the portable software instance or software instance is registered in z/OSMF, you can use z/OSMF Deployments to install the product software and create the product data sets (global, CSI, target libraries, and distribution libraries) for the new software instance. The deployment jobs create a copy of the source product data sets to create the product target runtime environment. Creating a copy of the SMP/E target data sets keeps the SMP/E environment clean and separates the product runtime environment for maintenance activities. You can also perform z/OSMF workflows to customize the SMP/E data sets, mount UNIX System Services (USS) files if necessary, and configure the new software instance on the target system. -To install Zowe PSWI using z/OSMF and make the product software available for use on a system by users and other programs, you need to define a new deployment. This step defines the SMP/E environment name and the prefix of the CSI data set in z/OSMF. Specify data set allocation parameters for all SMP/E data sets, target libraries, and distribution libraries. +## Prerequisite - Define a new deployment -To define a new deployment, complete the deployment checklist (specify the USS path, DSN, VOLSERs), and submit the deployment jobs through the z/OSMF user interface. When the deployment is complete, you have a source and target copy of the software. +To install Zowe PSWI using z/OSMF and make the product software available for use on a system by users and other programs, you first need to define a new deployment. This step defines the SMP/E environment name and the prefix of the CSI data set in z/OSMF. Specify data set allocation parameters for all SMP/E data sets, target libraries, and distribution libraries. -For more information about these tasks, see [Deploying software](https://www.ibm.com/docs/en/zos/2.4.0?topic=task-deploying-software) in the IBM documentation. +To define a new deployment, complete the deployment checklist as specified in [Deploying software](https://www.ibm.com/docs/en/zos/2.4.0?topic=task-deploying-software) in the IBM documentation. +Specify the following configuration elements: + +* UNIX System Services path (USS path) +* Data Set Name (DNS) +* Volume Serial Numbers (VOLSERs) + +Then submit the deployment jobs through the z/OSMF user interface. When the deployment is complete, you have a source and target copy of the software. Subsequent product maintenance activities update the SMP/E environment without affecting your active product runtime environments. You can decide when to redeploy the maintenance-updated SMP/E target data sets to each of the product runtime environments. @@ -62,8 +69,10 @@ Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-re 10. Specify the name and description of the new target software instance. - - All workflows that are mentioned in the previous steps are part of the PSWI. - **Note:** You do not have to execute all workflows during PSWI provisioning in z/OSMF immediately. +:::note Notes +* All workflows that are mentioned in the previous steps are part of the PSWI. +* You do not have to execute all workflows during PSWI provisioning in z/OSMF immediately. +::: The deployment process is complete. The new software instance is defined to z/OSMF. You are now ready to Import Product Information into z/OSMF before you install product maintenance. @@ -72,7 +81,7 @@ The deployment process is complete. The new software instance is defined to z/OS ### Cleanup If there is a need to update the deployment settings such as the HLQ after a previour run, consider that the deployment process does not perform a full cleanup of the datasets. -Before attempting it again, make sure the following datasets are deleted to avoid write conflicts: +Before attempting deployment again, make sure the following datasets are deleted to avoid write conflicts: ```plaintext {TARGET_HLQ}.PRODUCT.ZOWE.V2.CSI @@ -94,7 +103,16 @@ Before attempting it again, make sure the following datasets are deleted to avoi {TARGET_HLQ}.PRODUCT.ZOWE.V2.ZFS.# ``` -If deployment options must be modified and the JCL recreated, before doing so, check the original JCL for the temporary ZFS dataset name like `.SWDEPL..ZFS` and delete it manually. The deployment job will be unable to clean it once it is recreated because the random id will change. +If deployment options must be modified and the JCL recreated, first check the original JCL for the temporary ZFS dataset name. + +**Example:** +`.SWDEPL..ZFS` + + Delete this name manually. + + :::note + Note that the deployment job is unable to clean this data set name once this is recreated because the random id will change. + ::: ### Resources From 561f44a613685413209ca6bbe9869eec690175dc Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Tue, 3 Dec 2024 14:11:46 +0100 Subject: [PATCH 59/67] formatting fixes Signed-off-by: Andrew Jandacek --- docs/user-guide/install-zowe-pswi.md | 15 ++++++--------- .../user-guide/install-zowe-pswi.md | 15 ++++++--------- 2 files changed, 12 insertions(+), 18 deletions(-) diff --git a/docs/user-guide/install-zowe-pswi.md b/docs/user-guide/install-zowe-pswi.md index 3bb273b299..824b92475a 100644 --- a/docs/user-guide/install-zowe-pswi.md +++ b/docs/user-guide/install-zowe-pswi.md @@ -19,20 +19,17 @@ To install Zowe using z/OSMF, ensure that you meet the following requirements: Refer to the following subpages to guide you through the installation procedure using z/OSMF. -- [Address z/OSMF Requirements](./install-zowe-pswi-address-requirements.md) - +- [Address z/OSMF Requirements](./install-zowe-pswi-address-requirements.md) Provides information about z/OSMF general configuration and security requirements. -- [Acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire.md) - +- [Acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire.md) Provides the steps to acquire the product software by downloading the z/OSMF portable software instance to the z/OSMF host. You must then register the portable software instance in z/OSMF. -- [Install Product Software Using z/OSMF Deployments](./install-zowe-pswi-deployment.md) - +- [Install Product Software Using z/OSMF Deployments](./install-zowe-pswi-deployment.md) Provides the steps to install (deploy) the portable software instance to an LPAR using z/OSMF Deployments. This step creates the SMP/E environment and runs the RECEIVE, APPLY, and ACCEPT steps to prepare the software instance for SMP/E operations. This step also: -- Customizes the data set names that are defined to SMP/E. -- Mounts required USS files if necessary. -- Performs workflow execution to customize the deployed runtime environment for use on a specific z/OS system. + - Customizes the data set names that are defined to SMP/E. + - Mounts required USS files if necessary. + - Performs workflow execution to customize the deployed runtime environment for use on a specific z/OS system. When these tasks are completed, you are ready to install preventive maintenance. diff --git a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi.md b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi.md index 3bb273b299..824b92475a 100644 --- a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi.md +++ b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi.md @@ -19,20 +19,17 @@ To install Zowe using z/OSMF, ensure that you meet the following requirements: Refer to the following subpages to guide you through the installation procedure using z/OSMF. -- [Address z/OSMF Requirements](./install-zowe-pswi-address-requirements.md) - +- [Address z/OSMF Requirements](./install-zowe-pswi-address-requirements.md) Provides information about z/OSMF general configuration and security requirements. -- [Acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire.md) - +- [Acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire.md) Provides the steps to acquire the product software by downloading the z/OSMF portable software instance to the z/OSMF host. You must then register the portable software instance in z/OSMF. -- [Install Product Software Using z/OSMF Deployments](./install-zowe-pswi-deployment.md) - +- [Install Product Software Using z/OSMF Deployments](./install-zowe-pswi-deployment.md) Provides the steps to install (deploy) the portable software instance to an LPAR using z/OSMF Deployments. This step creates the SMP/E environment and runs the RECEIVE, APPLY, and ACCEPT steps to prepare the software instance for SMP/E operations. This step also: -- Customizes the data set names that are defined to SMP/E. -- Mounts required USS files if necessary. -- Performs workflow execution to customize the deployed runtime environment for use on a specific z/OS system. + - Customizes the data set names that are defined to SMP/E. + - Mounts required USS files if necessary. + - Performs workflow execution to customize the deployed runtime environment for use on a specific z/OS system. When these tasks are completed, you are ready to install preventive maintenance. From 0180c9b1283134a38270d4a44dd50d5d28193c0d Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Tue, 3 Dec 2024 16:26:42 +0100 Subject: [PATCH 60/67] minor fixes Signed-off-by: Andrew Jandacek --- .../version-v2.18.x/user-guide/configure-sysplex.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/versioned_docs/version-v2.18.x/user-guide/configure-sysplex.md b/versioned_docs/version-v2.18.x/user-guide/configure-sysplex.md index d78713b14c..e45e2f3e9c 100644 --- a/versioned_docs/version-v2.18.x/user-guide/configure-sysplex.md +++ b/versioned_docs/version-v2.18.x/user-guide/configure-sysplex.md @@ -10,13 +10,13 @@ Zowe high availability instances require a Sysplex environment that consists of - 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) +- 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) - Not required if using infinispan as Caching Service solution. VSAM storage for the Caching Service is deprecated and will be removed in a future release. -- 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) +- 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) +- z/OSMF high availability. See [Configuring z/OSMF high availability in Sysplex](systemrequirements-zosmf-ha.md) - Node.js v14.x (except v14.17.2), or v16.x :::note @@ -42,8 +42,7 @@ The following example DVIPA configuration ensures the availability of Zowe in Ho x.x.x.B BACKUP ENDVIPADYNAMIC ``` - - where, + - **x.x.x.A** Specifies the home address for SYSA. From 91a83d9d42966689892a8d5ecf0edfb2fda2535f Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Tue, 3 Dec 2024 16:40:35 +0100 Subject: [PATCH 61/67] make v3 and v2.18 intro consistent Signed-off-by: Andrew Jandacek --- .../user-guide/install-zowe-pswi-deployment.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md index e55e558308..f2a2fd312b 100644 --- a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md +++ b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md @@ -7,9 +7,14 @@ After the portable software instance or software instance is registered in z/OSM To install Zowe PSWI using z/OSMF and make the product software available for use on a system by users and other programs, you need to define a new deployment. This step defines the SMP/E environment name and the prefix of the CSI data set in z/OSMF. Specify data set allocation parameters for all SMP/E data sets, target libraries, and distribution libraries. -To define a new deployment, complete the deployment checklist (specify the USS path, DSN, VOLSERs), and submit the deployment jobs through the z/OSMF user interface. When the deployment is complete, you have a source and target copy of the software. +To define a new deployment, complete the deployment checklist as specified in [Deploying software](https://www.ibm.com/docs/en/zos/2.4.0?topic=task-deploying-software) in the IBM documentation. +Specify the following configuration elements: -For more information about these tasks, see [Deploying software](https://www.ibm.com/docs/en/zos/2.4.0?topic=task-deploying-software) in the IBM documentation. +* UNIX System Services path (USS path) +* Data Set Name (DNS) +* Volume Serial Numbers (VOLSERs) + +Then submit the deployment jobs through the z/OSMF user interface. When the deployment is complete, you have a source and target copy of the software. Subsequent product maintenance activities update the SMP/E environment without affecting your active product runtime environments. You can decide when to redeploy the maintenance-updated SMP/E target data sets to each of the product runtime environments. @@ -71,7 +76,7 @@ The deployment process is complete. The new software instance is defined to z/OS ### Cleanup -If the job execution fails, the deployment process does not perform a full cleanup of the datasets, before attempting job execution again, make sure the following datasets are deleted: +If the job execution fails, the deployment process does not perform a full cleanup of the datasets. Before attempting job execution again, make sure the following datasets are deleted: ```plaintext {TARGET_HLQ}.D.AZWEAUTH.# From 766e895548292ec03aae9df60c60a4c84b7ff6f6 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 4 Dec 2024 10:41:49 +0100 Subject: [PATCH 62/67] add prerequisite section header for v2.18 pswi-deployment Signed-off-by: Andrew Jandacek --- docs/user-guide/install-zowe-pswi-deployment.md | 6 +++--- .../user-guide/install-zowe-pswi-deployment.md | 5 ++++- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/install-zowe-pswi-deployment.md b/docs/user-guide/install-zowe-pswi-deployment.md index 2a3ce71e5e..131ecabbe7 100644 --- a/docs/user-guide/install-zowe-pswi-deployment.md +++ b/docs/user-guide/install-zowe-pswi-deployment.md @@ -20,7 +20,7 @@ Then submit the deployment jobs through the z/OSMF user interface. When the depl Subsequent product maintenance activities update the SMP/E environment without affecting your active product runtime environments. You can decide when to redeploy the maintenance-updated SMP/E target data sets to each of the product runtime environments. -Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-requirements#confirm-that-the-installer-has-read-create-update-and-execute-privileges-in-zos) are met. +Before installing, ensure the [z/OSMF requirements](./install-zowe-pswi-address-requirements.md#confirm-that-the-installer-has-read-create-update-and-execute-privileges-in-zos) are met. ## Installing process @@ -80,8 +80,8 @@ The deployment process is complete. The new software instance is defined to z/OS ### Cleanup -If there is a need to update the deployment settings such as the HLQ after a previour run, consider that the deployment process does not perform a full cleanup of the datasets. -Before attempting deployment again, make sure the following datasets are deleted to avoid write conflicts: +If there is a need to update the deployment settings such as the HLQ after a previous run, note that the deployment process does not perform a full cleanup of the datasets. +Before attempting job execution again, make sure the following datasets are deleted to avoid write conflicts: ```plaintext {TARGET_HLQ}.PRODUCT.ZOWE.V2.CSI diff --git a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md index f2a2fd312b..4f8b5cd480 100644 --- a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md +++ b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md @@ -5,6 +5,8 @@ After the portable software instance or software instance is registered in z/OSMF, you can use z/OSMF Deployments to install the product software and create the product data sets (global, CSI, target libraries, and distribution libraries) for the new software instance. The deployment jobs create a copy of the source product data sets to create the product target runtime environment. Creating a copy of the SMP/E target data sets keeps the SMP/E environment clean and separates the product runtime environment for maintenance activities. You can also perform z/OSMF workflows to customize the SMP/E data sets, mount UNIX System Services (USS) files if necessary, and configure the new software instance on the target system. +## Prerequisite - Define a new deployment + To install Zowe PSWI using z/OSMF and make the product software available for use on a system by users and other programs, you need to define a new deployment. This step defines the SMP/E environment name and the prefix of the CSI data set in z/OSMF. Specify data set allocation parameters for all SMP/E data sets, target libraries, and distribution libraries. To define a new deployment, complete the deployment checklist as specified in [Deploying software](https://www.ibm.com/docs/en/zos/2.4.0?topic=task-deploying-software) in the IBM documentation. @@ -18,7 +20,8 @@ Then submit the deployment jobs through the z/OSMF user interface. When the depl Subsequent product maintenance activities update the SMP/E environment without affecting your active product runtime environments. You can decide when to redeploy the maintenance-updated SMP/E target data sets to each of the product runtime environments. -Before installing, ensure the [z/OSMF requirements](install-zowe-pswi-address-requirements#confirm-that-the-installer-has-read-create-update-and-execute-privileges-in-zos) are met. +Before installing, ensure the [z/OSMF requirements](./install-zowe-pswi-address-requirements.md#confirm-that-the-installer-has-read-create-update-and-execute-privileges-in-zos) +are met. ## Installing process From 5f9ba805743db752a011d6bb34857a96f4637af6 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Wed, 4 Dec 2024 16:04:55 +0530 Subject: [PATCH 63/67] Update systemrequirements-zosmf-lite.md (#4020) * Update systemrequirements-zosmf-lite.md Removed the 3 bullets, namely: -Microsoft Internet Explorer Version 11 or later. -Microsoft Edge (Windows 10). -Mozilla Firefox ESR Version 52 or later. Added a link to a page in the IBM documentation. This page lists the browsers supported by zosmf. * minor language correction Signed-off-by: Andrew Jandacek --------- Signed-off-by: Andrew Jandacek Co-authored-by: Andrew Jandacek --- docs/user-guide/systemrequirements-zosmf-lite.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/user-guide/systemrequirements-zosmf-lite.md b/docs/user-guide/systemrequirements-zosmf-lite.md index 0213478be3..69a5bd151b 100644 --- a/docs/user-guide/systemrequirements-zosmf-lite.md +++ b/docs/user-guide/systemrequirements-zosmf-lite.md @@ -86,13 +86,7 @@ Otherwise, you might encounter errors later in the process. If you encounter err ### Web browser -For the best results with z/OSMF, use one of the following web browsers on your workstation: - -- Microsoft Internet Explorer Version 11 or later - -- Microsoft Edge (Windows 10) - -- Mozilla Firefox ESR Version 52 or later. +For best results with z/OSMF, use one of the [web browsers supported by z/OSMF](https://www.ibm.com/docs/en/zos/3.1.0?topic=zosmf-software-prerequisites#SoftwarePrerequisites__title__4). To check your web browser's level, click **About** in the web browser. From 8698675f9a3704249a9c8d045544aadca83639bd Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 4 Dec 2024 13:37:10 +0100 Subject: [PATCH 64/67] change note Signed-off-by: Andrew Jandacek --- docs/user-guide/install-zowe-pswi-deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/install-zowe-pswi-deployment.md b/docs/user-guide/install-zowe-pswi-deployment.md index 131ecabbe7..ae9e18ce1a 100644 --- a/docs/user-guide/install-zowe-pswi-deployment.md +++ b/docs/user-guide/install-zowe-pswi-deployment.md @@ -111,7 +111,7 @@ If deployment options must be modified and the JCL recreated, first check the or Delete this name manually. :::note - Note that the deployment job is unable to clean this data set name once this is recreated because the random id will change. + Note that the deployment job is unable to clean this data set name once the data set is recreated because the value for `random_id` will change. ::: ### Resources From 7af1ad660c2b7303042332c93fdb00e792263a2f Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 4 Dec 2024 14:26:27 +0100 Subject: [PATCH 65/67] fix anchor link in installation checklist dev to fix broken link report Signed-off-by: Andrew Jandacek --- docs/user-guide/zos-components-installation-checklist-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/zos-components-installation-checklist-dev.md b/docs/user-guide/zos-components-installation-checklist-dev.md index bf36e325f8..346605fb50 100644 --- a/docs/user-guide/zos-components-installation-checklist-dev.md +++ b/docs/user-guide/zos-components-installation-checklist-dev.md @@ -43,7 +43,7 @@ Use one of the following installation options to install Zowe z/OS components. | Verification Step | Task | Results | Time Estimate | |----|-----------|----|-------------| | [Verify Zowe Application Framework installation](../user-guide/verify-zowe-runtime-install.md#verifying-zowe-application-framework-installation) | Open the Zowe Desktop from a supported browser | You should be able to open the Zowe Desktop from a supported browser. | 20 minutes| -| [Verify API Mediation installation](../user-guide/verify-zowe-runtime-install.md#verifying-api-mediation-installation) |Use a REST API client to review the value of the status variable of the API Catalog service routed through the API Gateway | See the example presented in Verify API Mediation installation | 15 minutes | +| [Verify API Mediation installation](../user-guide/verify-zowe-runtime-install.md#verifying-api-mediation-layer-installation) |Use a REST API client to review the value of the status variable of the API Catalog service routed through the API Gateway | See the example presented in Verify API Mediation installation | 15 minutes | |[Verify z/OS Services installation](../user-guide/verify-zowe-runtime-install.md#verifying-zos-services-installation) |Zowe z/OS services usually are registered with Zowe APIML Discovery| You should see JSON format data of all jobs running on the system | 15 minutes | From cd5f71bf20f0f7d791fd9372cbc3e175f711fb4f Mon Sep 17 00:00:00 2001 From: Richard Salac Date: Wed, 4 Dec 2024 14:46:18 +0100 Subject: [PATCH 66/67] sync v3 pswi deployment with v2.18 --- .../install-zowe-pswi-deployment.md | 49 +++++++++++++------ 1 file changed, 34 insertions(+), 15 deletions(-) diff --git a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md index 4f8b5cd480..b5ab00160a 100644 --- a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md +++ b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md @@ -70,8 +70,10 @@ are met. 10. Specify the name and description of the new target software instance. - - All workflows that are mentioned in the previous steps are part of the PSWI. - **Note:** You do not have to execute all workflows during PSWI provisioning in z/OSMF immediately. +:::note Notes + * All workflows that are mentioned in the previous steps are part of the PSWI. + * You do not have to execute all workflows during PSWI provisioning in z/OSMF immediately. +::: The deployment process is complete. The new software instance is defined to z/OSMF. You are now ready to Import Product Information into z/OSMF before you install product maintenance. @@ -79,23 +81,40 @@ The deployment process is complete. The new software instance is defined to z/OS ### Cleanup -If the job execution fails, the deployment process does not perform a full cleanup of the datasets. Before attempting job execution again, make sure the following datasets are deleted: +If there is a need to update the deployment settings such as the HLQ after a previous run, note that the deployment process does not perform a full cleanup of the datasets. +Before attempting job execution again, make sure the following datasets are deleted to avoid write conflicts: ```plaintext -{TARGET_HLQ}.D.AZWEAUTH.# -{TARGET_HLQ}.D.AZWEZFS.# -{TARGET_HLQ}.SMPLOG.# -{TARGET_HLQ}.SMPLOGA.# -{TARGET_HLQ}.SMPLTS.# -{TARGET_HLQ}.SMPMTS.# -{TARGET_HLQ}.SMPSCDS.# -{TARGET_HLQ}.T.SZWEAUTH.# -{TARGET_HLQ}.T.SZWEEXEC.# -{TARGET_HLQ}.T.SZWELOAD.# - -{TARGET_HLQ}.CSI.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.CSI +{TARGET_HLQ}.PRODUCT.ZOWE.V2.D.AZWEAUTH.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.D.AZWESAMP.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.D.AZWEZFS.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPLOG.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPLOGA.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPLTS.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPMTS.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPPTS.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPSCDS.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.SMPSTS.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.T.SZWEAUTH.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.T.SZWEEXEC.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.T.SZWELOAD.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.T.SZWESAMP.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.WORKFLOW.# +{TARGET_HLQ}.PRODUCT.ZOWE.V2.ZFS.# ``` +If deployment options must be modified and the JCL recreated, first check the original JCL for the temporary ZFS dataset name. + +**Example:** +`.SWDEPL..ZFS` + +Delete this name manually. + +:::note +Note that the deployment job is unable to clean this data set name once this is recreated because the random id will change. +::: + ### Resources It is recommended to update the job card to run with `REGION=0M`, particularly for job `IZUD01DZ` which unpaxes the contents. From 8dcf93879d3d9f562988eeab2d90f43b7bad651f Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 4 Dec 2024 14:54:55 +0100 Subject: [PATCH 67/67] update note in v2.18 Signed-off-by: Andrew Jandacek --- .../user-guide/install-zowe-pswi-deployment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md index b5ab00160a..ddf71495bb 100644 --- a/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md +++ b/versioned_docs/version-v2.18.x/user-guide/install-zowe-pswi-deployment.md @@ -111,8 +111,8 @@ If deployment options must be modified and the JCL recreated, first check the or Delete this name manually. -:::note -Note that the deployment job is unable to clean this data set name once this is recreated because the random id will change. +:::note +Note that the deployment job is unable to clean this data set name once the data set is recreated because the value for `random_id` will change. ::: ### Resources