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) diff --git a/docs/user-guide/apf-authorize-load-library.md b/docs/user-guide/apf-authorize-load-library.md index f95c51b891..7a5a1d81b9 100644 --- a/docs/user-guide/apf-authorize-load-library.md +++ b/docs/user-guide/apf-authorize-load-library.md @@ -27,11 +27,9 @@ 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. +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. ::: -Specify `--security-dry-run` to have the command echo the commands that need to be run without executing the command. - ``` SETPROG APF,ADD,DSNAME=IBMUSER.ZWEV2.SZWEAUTH,SMS SETPROG APF,ADD,DSNAME=IBMUSER.ZWEV2.CUST.ZWESAPL,SMS diff --git a/docs/user-guide/assign-security-permissions-to-users.md b/docs/user-guide/assign-security-permissions-to-users.md index 20323ddaac..700ede0f6c 100644 --- a/docs/user-guide/assign-security-permissions-to-users.md +++ b/docs/user-guide/assign-security-permissions-to-users.md @@ -15,16 +15,16 @@ The following user IDs run Zowe: * **ZWESVUSR** This is the started task ID of the Zowe runtime user who runs most of the Zowe core - components. - 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. @@ -58,8 +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) | - - ## 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). @@ -75,12 +73,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: ``` @@ -88,12 +94,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 3bcd4a2e92..372e67b9f7 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 +# 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 ::: + +:::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,27 +33,48 @@ 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. - -| 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) | + 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) | + +### 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 @@ -357,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. @@ -462,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:
@@ -507,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. @@ -562,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. @@ -611,9 +640,9 @@ If you have run `ZWESECUR` you do not need to perform the steps described in thi If you have not run `ZWESECUR` and are configuring your z/OS environment manually, the following steps describe how to configure the cross memory server for SAF. -Activate the FACILITY class, define a `ZWES.IS` profile, and grant READ access to the user ID `ZWESVUSR`. This is the user ID that the 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. @@ -689,8 +718,8 @@ 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. -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:
Click here for procedure details for RACF. @@ -699,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) ``` @@ -723,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) ``` @@ -748,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) ``` @@ -761,8 +790,8 @@ If you use TSS, verify and update permission in `FACILITY` class. ### 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:
Click here for procedure details for RACF. @@ -771,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 ``` @@ -840,18 +869,24 @@ If you use TSS, verify and update permission in `FACILITY` class. ### 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 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_ 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). -* **Top Secret** - _**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). -* **ACF2** - _**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). + +* **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. @@ -872,24 +907,24 @@ To set up this security configuration, submit the `ZWESECUR` JCL member. For use
- Click here for command details for Top Secret. + Click here for command details for ACF2. - If you use Top Secret, issue the following command: + If you use ACF2, issue the following commands: ``` - TSS WHOHAS IBMFAC(IRR.RAUDITX) + SET RESOURCE(FAC) + ``` + ``` + LIST LIKE(IRR-) ```
- Click here for command details for ACF2. + Click here for command details for Top Secret. - If you use ACF2, issue the following commands: - ``` - SET RESOURCE(FAC) - ``` + If you use Top Secret, issue the following command: ``` - LIST LIKE(IRR-) + TSS WHOHAS IBMFAC(IRR.RAUDITX) ```
@@ -914,16 +949,6 @@ To set up this security configuration, submit the `ZWESECUR` JCL member. For use
-
- 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) - ``` - -
-
Click here for command details for ACF2. @@ -938,7 +963,19 @@ To set up this security configuration, submit the `ZWESECUR` JCL member. For use 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. @@ -966,5 +1003,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/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 diff --git a/docs/user-guide/configuring-overview.md b/docs/user-guide/configuring-overview.md index 1738b1099f..e2ae271675 100644 --- a/docs/user-guide/configuring-overview.md +++ b/docs/user-guide/configuring-overview.md @@ -23,17 +23,17 @@ 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 via JCL** You can configure Zowe by directly customizing JCLs. The Zowe Runtime Dataset `SZWESAMP` contains JCL samples that have templates referencing `zowe.yaml` parameters. These samples should not be submitted without modification. -For more information, see [Configuring Zowe via JCL](./configuring-zowe-via-jcl.md) + For more information, see [Configuring Zowe via JCL](./configuring-zowe-via-jcl.md) * **Option 3: 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 [Configuring Zowe with z/OSMF Workflows](./configure-zowe-zosmf-workflow.md). + For more information, see [Configuring Zowe with z/OSMF Workflows](./configure-zowe-zosmf-workflow.md). ## Configuring the z/OS system for Zowe diff --git a/docs/user-guide/configuring-security.md b/docs/user-guide/configuring-security.md index 221504a5c2..aa84dfe5d2 100644 --- a/docs/user-guide/configuring-security.md +++ b/docs/user-guide/configuring-security.md @@ -2,33 +2,121 @@ 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 -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 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,15 +136,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). 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 349f87b80c..cdcba9fe90 100644 --- a/docs/user-guide/initialize-zos-system.md +++ b/docs/user-guide/initialize-zos-system.md @@ -23,7 +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 + ::: :::tip @@ -34,13 +35,13 @@ Enter `zwe init --help` to learn more about the command or see the [`zwe init` c The following `zwe init` arguments can assist you with the initization process: -- **--update-config** +- **--update-config** This argument allows the init process to update your configuration file based on automatic detection and your `zowe.setup` settings. For example, if `java.home` and `node.home` are not defined, they can be updated based on the information that is collected on the system. `zowe.certificate` section can also be updated automatically based on your `zowe.setup.certificate` settings. -- **--allow-overwrite** +- **--allow-overwrite** This argument allows you to rerun the `zwe init` command repeatedly regardless of whether some data sets are already created. -- **-v** or **--verbose** +- **-v** or **--verbose** This argument provides execution details of the `zwe` command. You can use it for troubleshooting purposes if the error message is not clear enough. -- **-vv** or **--trace** +- **-vv** or **--trace** This argument provides you more execution details than the `--verbose` mode for troubleshooting purposes. ## Zowe initilization command diff --git a/docs/user-guide/systemrequirements-zos.md b/docs/user-guide/systemrequirements-zos.md index acfd4521fa..58930418a5 100644 --- a/docs/user-guide/systemrequirements-zos.md +++ b/docs/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 [Security customization of your z/OS system](./configure-zos-system.md). +::: diff --git a/docs/user-guide/verify-zowe-runtime-install.md b/docs/user-guide/verify-zowe-runtime-install.md index b8fc189e12..43d5b9e67e 100644 --- a/docs/user-guide/verify-zowe-runtime-install.md +++ b/docs/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`. To verify a service is necessary to call any available endpoint, for example: @@ -71,8 +77,9 @@ To verify a service is necessary to call any available endpoint, for example: https://hostName:gatewayPort/serviceId/api/v1/version ``` -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 path `serviceId/api/v1/version` depends on a specific service. You can also use API Catalog to verify a registered service. 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 | diff --git a/docs/user-guide/zwe-init-subcommand-overview.md b/docs/user-guide/zwe-init-subcommand-overview.md index fa21b906c8..075a006b77 100644 --- a/docs/user-guide/zwe-init-subcommand-overview.md +++ b/docs/user-guide/zwe-init-subcommand-overview.md @@ -6,11 +6,13 @@ 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) +- [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`) @@ -28,7 +30,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 following `zowe.yaml` section contains the parameters for the data set names: ```yaml zowe: @@ -83,7 +85,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`. @@ -108,7 +110,34 @@ 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`) @@ -122,10 +151,43 @@ The command `zwe init apfauth` reads the PDS names for the following load librar * **zowe.setup.dataset.authLoadLib** Specifies the user custom load library, containing the ZWELNCH, ZWESIS01 and ZWESAUX load modules. These are the Zowe launcher, the ZIS cross memory server and the auxiliary server. -* **zowe.setup.dataset.authPluginLib** +* **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`) @@ -136,7 +198,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`) 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",