Merge pull request #4019 from zowe/janan07/apply-security-config-reor…

…g-to-2.18

apply security config reorg to 2.18

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

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
 

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
 

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
+<details>
+<summary>Click here to configure with the `zwe init security` command.</summary>
+
+**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.
+#>
+```
+:::
+
+</details>
+
+<!-- Validate is the following section should be removed -->
+
+<details>
+<summary>Click here to configure with `ZWESECUR` JCL.<!-- Validate if this method should be removed --> </summary>
+
+
+**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.
+
+<iframe class="embed-responsive-item" id="youtubeplayer" title="Zowe ZWESECUR configure system for security (one-time)" type="text/html" width="640" height="390" src="https://www.youtube.com/embed/-7PZFVESitI" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen="true"> </iframe>
+
+</details>
+
+<!-- Validate if the following section should be revised or removed -->
+:::tip
+
+If an error occured in performing security configuration, these configurations can be undone. 
+<details>
+<summary>Click here for details about undoing security configurations.</summary>
+
+
+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. 
+
+</details>
+
+:::
 
 ## 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).
 
 
 

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

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).
+:::