diff --git a/.github/workflows/link-checker.yml b/.github/workflows/link-checker.yml index 3f4f08beb7..abd30d3329 100644 --- a/.github/workflows/link-checker.yml +++ b/.github/workflows/link-checker.yml @@ -26,12 +26,12 @@ jobs: done - name: Restore lychee cache - uses: actions/cache@v4 + id: lychee-cache-restore + uses: actions/cache/restore@v4 with: path: .lycheecache - key: cache-lychee-${{ github.base_ref || github.ref_name }} + key: cache-lychee-${{ github.event.pull_request.head.ref || github.base_ref || github.ref_name }} restore-keys: cache-lychee- - save-always: true - name: Run lychee uses: lycheeverse/lychee-action@v1 @@ -39,3 +39,11 @@ jobs: args: "--accept 403,406,429 --cache --include-fragments --max-cache-age 1d --max-concurrency 2 --no-progress --timeout 60 --verbose 'docs/**/*.md'" fail: true token: ${{ secrets.GITHUB_TOKEN }} + + - name: Always save lychee cache + id: save-lychee-cache + if: always() + uses: actions/cache/save@v4 + with: + key: ${{ steps.lychee-cache-restore.outputs.cache-primary-key }} + path: .lycheecache diff --git a/docs/images/zosmf/inputvars-jcl-enable.png b/docs/images/zosmf/inputvars-jcl-enable.png new file mode 100644 index 0000000000..d36d55115f Binary files /dev/null and b/docs/images/zosmf/inputvars-jcl-enable.png differ diff --git a/docs/user-guide/cli-authentication-methods.md b/docs/user-guide/cli-authentication-methods.md index 02853b5af4..86c37b8de4 100644 --- a/docs/user-guide/cli-authentication-methods.md +++ b/docs/user-guide/cli-authentication-methods.md @@ -14,7 +14,7 @@ If you configure multiple authentication methods for a specific service, set the ## Order of precedence -You can configure the order that Zowe CLI follows to search for an available authentication method, or you can leave the [default order of precedence](../extend/extend-cli/cli-authentication-mechanisms.md#default-order-of-precendence) used by the service you are connecting to. +You can configure the order that Zowe CLI follows to search for an available authentication method, or you can leave the [default order of precedence](../extend/extend-cli/cli-authentication-mechanisms.md#default-order-of-precedence) used by the service you are connecting to. To configure a different order of precedence, add the `authOrder` property to the profile for the service to which you want to connect.: diff --git a/docs/user-guide/configure-apiml-zosmf-workflow.md b/docs/user-guide/configure-apiml-zosmf-workflow.md index 6c8e357f5f..de4702f7ff 100644 --- a/docs/user-guide/configure-apiml-zosmf-workflow.md +++ b/docs/user-guide/configure-apiml-zosmf-workflow.md @@ -14,6 +14,10 @@ Ensure that you meet the following requirements before you start your Zowe confi - Install and configure z/OSMF - Install Zowe with an SMP/E build, PSWI, or a convenience build +:::note +From Zowe 3.3.0 forward, the Zowe z/OSMF Workflow supports JCL-driven configuration. This will become the default method of configuration in a future release. Read [this guide](./configuring-zowe-via-jcl.md#following-existing-zosmf-workflow-documentation) for more information. +::: + ## Overview of Stand-alone Zowe API ML Configuration workflow The following components are automatically enabled after performing the **Stand-alone Zowe API ML Configuration** workflow: diff --git a/docs/user-guide/configure-zowe-runtime.md b/docs/user-guide/configure-zowe-runtime.md index 0255c92e18..bda15dc8ed 100644 --- a/docs/user-guide/configure-zowe-runtime.md +++ b/docs/user-guide/configure-zowe-runtime.md @@ -7,7 +7,7 @@ Begin configuration of your installation of Zowe z/OS components by initializing Use one of the following options to initialize Zowe z/OS runtime: -* Initialize Zowe maunually using zwe init command group +* Initialize Zowe manually using zwe init command group * Configure Zowe with z/OSMF workflows ## Initialize Zowe manually using zwe init command group @@ -18,7 +18,7 @@ After your installation of Zowe runtime, you can run the `zwe init` command to p * 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 Zowe caching service for high availability (HA) * Configure the system to launch the Zowe started task For more information about this z/OS runtime initialization method, see [Configuring Zowe with zwe init](./initialize-zos-system.md) diff --git a/docs/user-guide/configure-zowe-zosmf-workflow.md b/docs/user-guide/configure-zowe-zosmf-workflow.md index d8a931bdd0..ee877dbf1c 100644 --- a/docs/user-guide/configure-zowe-zosmf-workflow.md +++ b/docs/user-guide/configure-zowe-zosmf-workflow.md @@ -15,6 +15,10 @@ Ensure that you meet the following requirements before you start your Zowe confi - Install and configure z/OSMF - Install Zowe with an SMP/E build, PSWI, or a convenience build +:::note +From Zowe 3.3.0 forward, the Zowe z/OSMF Workflow supports JCL-driven actions. This will become the default method of configuration in a future release. Read [this guide](./configuring-zowe-via-jcl.md#following-existing-zosmf-workflow-documentation) for more information. +::: + ## Overview of Full Zowe server-side configuration for Zowe 3.0 workflow You can complete the following tasks with the **Full Zowe server-side configuration for Zowe 3.0** workflow: diff --git a/docs/user-guide/configuring-overview.md b/docs/user-guide/configuring-overview.md index ee78144c88..91e8fe2647 100644 --- a/docs/user-guide/configuring-overview.md +++ b/docs/user-guide/configuring-overview.md @@ -18,17 +18,21 @@ Successful completion of steps 2, 3, and 4 may require elevated security permiss ## Configuring Zowe runtime -To cofigure Zowe runtime, choose from the following options: +To configure 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_. +* **Option 1: Configure Zowe 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 [Zowe configuration file](./installandconfig.md#zowe-configuration-file-zoweyaml). 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** +:::note +From Zowe 3.3.0 forward, the `zwe init` command supports JCL-driven actions. This will become the default method of `zwe init` configuration in a future release. Read [this guide](./configuring-zowe-via-jcl.md) to get started. +::: + +* **Option 2: Configure Zowe via manual 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#getting-started-with-manual-jcl-submission) * **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. @@ -43,7 +47,7 @@ You can execute the Zowe configuration workflow either from a PSWI during deploy Configuration of the z/OS system is dependent on the specific Zowe features and functionalities you would like to employ with your Zowe installation. :::tip -Note that configuring the z/OS system requires elevated permissions. We recommend you consult with your security administrator to perform the reqired steps to configure the z/OS system. +Note that configuring the z/OS system requires elevated permissions. We recommend you consult with your security administrator to perform the required steps to configure the z/OS system. ::: For more information, see [Configuring the z/OS system for Zowe](./configure-zos-system.md). diff --git a/docs/user-guide/configuring-zowe-via-jcl.md b/docs/user-guide/configuring-zowe-via-jcl.md index b9cd1c0b35..dececb9a2b 100644 --- a/docs/user-guide/configuring-zowe-via-jcl.md +++ b/docs/user-guide/configuring-zowe-via-jcl.md @@ -1,6 +1,131 @@ - # Configuring Zowe via JCL +# Configuring Zowe with JCL -One option to configure Zowe is 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. Samples that are submitted without modification will end unsuccessfully with a JCL ERROR status. +:::note +Configuring Zowe with JCL is currently in *technical preview*. In a later release, this will become the default method of configuration. +::: + +Zowe can be configured on your system with JCL using the `zwe` commands, or by customizing and running JCL entirely manually. Both of these configuration methods require a [`zowe.yaml` configuration file](./installandconfig.md#zowe-configuration-file-zoweyaml). Between these two options, we recommend sticking with `zwe` commands rather than manually submitting JCL, as there's additional validation `zwe` can perform on your configuration prior to creating and submitting JCL. + +- [Getting started with `zwe` and JCL](#getting-started-with-zwe-and-jcl) + - [Generating JCL](#generating-jcl) + - [Adding Job Parameters to generated JCL](#adding-job-parameters-to-generated-jcl) + - [Reviewing JCL before submission](#reviewing-jcl-before-submission) + - [Following existing `zwe` command documentation](#following-existing-zwe-command-documentation) + - [Following existing z/OSMF workflows](#following-existing-zosmf-workflow-documentation) +- [Getting started with manual JCL submission](#getting-started-with-manual-jcl-submission) + - [Preparing the JCL](#preparing-the-jcl) + - [Manual JCL Core Tasks](#manual-jcl-core-tasks) + - [Manual JCL Keyring Tasks](#manual-jcl-keyring-tasks) + - [Manual JCL Caching Service VSAM Task (Deprecated)](#manual-jcl-caching-service-vsam-task-deprecated) + +## Getting started with `zwe` and JCL + +By default, `zwe` will not submit solely JCL to configure Zowe, instead relying on a mix of unix services and JCL. To enable `zwe` to rely **solely** on JCL, you can either add `--jcl` to the end of every `zwe install` or `zwe init` command, or set `zowe.setup.jcl.enable` in your `zowe.yaml` file. + +Example `zowe.yaml`: +```yaml +zowe: + setup: + jcl: + enable: true +``` + +Example commands: `--jcl` overrides `zowe.setup.jcl.enable` +```shell +zwe install -c /path/to/my/zowe.yaml --jcl +zwe init mvs -c /path/to/my/zowe.yaml --jcl +``` + +### Generating JCL + +Running `zwe init` commands with JCL require that you to first generate JCL using values present in your `zowe.yaml` file. To do this, run: + +```shell +zwe init generate -c /path/to/my/zowe.yaml +``` + +This takes the configuration values present in your `zowe.yaml` file, uses them to populate JCL templates in `SZWESAMP`, and creates a `JCLLIB` data set with the final generated JCL. The `JCLLIB` will be created using the value of `zowe.setup.dataset.jcllib`. + +For example, `zwe init generate` with the below `zowe.yaml` creates the dataset `MY.DS.PREFIX.JCLLIB`. If this data set already exists, it is always overwritten by `init generate` command. +```yaml +zowe: + setup: + dataset: + # ... other fields + jcllib: MY.DS.PREFIX.JCLLIB +``` + +:::important +If you make any changes to values which begin with `zowe.setup` in your `zowe.yaml` file, you must re-run `zwe init generate` to create fresh JCL. Optionally, `zwe init` commands provide a `--generate` flag which will run `init generate` on-the-fly as well. For example, `zwe init mvs --generate` will run `init generate` before the `init mvs`. +::: + +### Adding Job Parameters to generated JCL + +If you require specific job parameters to run JCL on your system, you can add them via the `zowe.setup.jcl.header` field in your `zowe.yaml` file. The `zwe` commands _will not_ validate the syntax of the supplied parameters, so you should always review the generated JCL to ensure the headers are correct. + +This header field can be supplied as either a single or multi-line string. The first line requires no formatting, while next lines require you to follow JCL syntax. If using a single line for the header field, use `\n` to indicate new lines. If using multi-line strings, ensure your indentation remains aligned with each new line. + +Example `zowe.yaml`, with header as a single line: +```yaml +zowe: + setup: + jcl: + enable: true + # Double quotes are required around the entire string: + header: "'ZWECFJOB'\n// REGION=0M\n//* atestcomment" + dataset: # ...the rest of your zowe.yaml +``` + +Example `zowe.yaml`, with header as multi-line field: +```yaml +zowe: + setup: + jcl: + enable: true + # Ensure spacing is aligned here, column 1 is under the 'a' of 'header' + header: | + 'ZWECFJOB', + // REGION=0M + //* atestcomment + dataset: # ...the rest of your zowe.yaml +``` + +Both `zowe.yaml` files create the below job card: +```jcl +//ZWEGENER JOB 'ZWECFJOB', +// REGION=0M +//* atestcomment +``` + +### Reviewing JCL before submission + +One advantage to JCL is the ability to review all the actions it will take on your system before submitting it. There are a few ways to review JCL used by `zwe` before submission. All `zwe init` and `zwe install` commands support the `--dry-run` command line parameter, which will print the command's final JCL to the console and exit. When running `zwe init generate` or `zwe install` specifically, this is the only way to review the final JCL prior to submission. For other `zwe init` commands, you can choose to run them with `--dry-run` and review the console output, or you can review their JCL in the `JCLLIB` dataset created by `init generate`. We recommend reviewing using `--dry-run`, and inspecting the `JCLLIB` only if `--dry-run` is insufficient. + +### Following existing `zwe` command documentation + +To configure Zowe successfully with JCL, you can follow all existing documentation for `zwe install` and `zwe init` with minor modifications: + +1. Setup JCL enablement and JCL job parameters as described in this guide first. +2. Run `zwe init generate` before any other `init` command, and after any change to a `zowe.setup` field in the `zowe.yaml` file. + +Differences to note: + +1. `zwe init security` no longer submits `ZWESECUR`, and instead uses `ZWEI***`, where `***` is your configured ESM. + +### Following existing z/OSMF workflow documentation + +Both the [Zowe Configuration Workflow](https://docs.zowe.org/stable/user-guide/configure-apiml-zosmf-workflow) and the [Stand-alone APIML Workflow](https://docs.zowe.org/stable/user-guide/configure-apiml-zosmf-workflow) support configuration with JCL. When you start your configuration, you will see the option to enable JCL and a field labeled with `Job statement positional parameters...` where you can fill in job statement information. +**Note:** Do _not_ enter a start-of-line `// ` for lines 2 or later in the workflow text field; it will be added automatically for you. This entire text field can be left blank if you do not need to add any job statement parameters. Once you have reviewed and set these fields, follow the workflow instructions normally. + +![Workflow](../images/zosmf/inputvars-jcl-enable.png) + +## Getting started with manual JCL submission + +If you do not wish to use the `zwe` command-line tool to configure Zowe, you can submit the same set of JCL yourself directly through MVS data sets. Do note that you will still need a `zowe.yaml` file. + +### Preparing the JCL + +The Zowe Sample Data set `SZWESAMP` contains JCL samples that have templates referencing Zowe YAML parameters. These samples should not be submitted without modification. Samples that are submitted without modification will end unsuccessfully with a JCL ERROR status. Edit and submit the job `SZWESAMP(ZWEGENER)` to validate the contents of your `zowe.yaml` before resolving the `JCL templates` and placing the resulting JCL into a separate data set created by the job `ZWEGENER`. The location is specified in `zowe.setup.dataset.jcllib`. @@ -13,21 +138,21 @@ Edit and submit the job `SZWESAMP(ZWEGENER)` to validate the contents of your `z When the JCL is prepared, the following jobs can be submitted to perform the following instance configuration actions. In addition to core JCL samples, you can also customize JCL samples for various keyring setup options according to your security manager. -* For sample JCLs corresponding to core tasks, see the table [Core Tasks](#core-tasks). -* For sample JCLs corresponding to keyring tasks, see the section [Keyring Tasks](#keyring-tasks) later in this article. -* For JCL samples if you are using VSAM as your storage solution for the Caching service, see the table corresponding to [(Deprecated) Caching Service VSAM Task](#deprecated-caching-service-vsam-task). +* For sample JCLs corresponding to core tasks, see the table [Core Tasks](#manual-jcl-core-tasks). +* For sample JCLs corresponding to keyring tasks, see the section [Keyring Tasks](#manual-jcl-keyring-tasks) later in this article. +* For JCL samples if you are using VSAM as your storage solution for the Caching service, see the table corresponding to [(Deprecated) Caching Service VSAM Task](#manual-jcl-caching-service-vsam-task-deprecated). -## Core Tasks +## Manual JCL Core Tasks | Task | Description | Sample JCL| |------|-------------|-----------| -|Create Instance Datasets |
**Purpose:**
Create datasets for Zowe's PARMLIB content and non-ZFS extension content for a given Zowe Instance
**Action:**
1) Allocate the PDSE FB80 dataset with at least 15 tracks named from Zowe parameter `zowe.setup.dataset.parmlib`
2) Allocate the PDSE FB80 dataset with at least 30 tracks named from Zowe parameter `zowe.setup.dataset.authPluginLib`
3) Copy the member `ZWESIP00` from `zowe.setup.dataset.prefix.SZWESAMP` into `zowe.setup.dataset.parmlib` | [ZWEIMVS](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEIMVS) -|APF Authorize privileged content |
**Purpose:**
The majority of Zowe is unprivileged code running in Key 8. Zowe relies on a single component called ZIS to own all of the privileged code logic. The load library for the ZIS component and its extension library must be set as APF authorized and run in Key 4 to use ZIS and components that depend upon it.
**Action:**
1) APF authorize the datasets defined at `zowe.setup.dataset.authLoadlib` and `zowe.setup.dataset.authPluginLib`.
2) Define PPT entries for the members `ZWESIS01` and `ZWESAUX` as Key 4, NOSWAP in the `SCHEDxx` member of the system PARMLIB. | [ZWEIAPF](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEIAPF)
- Grant SAF premissions |
**Purpose:**
The STC accounts for Zowe need permissions for operating servers, and users need permissions for interacting with the servers.
**Action:**
[Set SAF permissions for accounts](https://docs.zowe.org/stable/user-guide/assign-security-permissions-to-users#security-permissions-reference-table) | RACF: [ZWEIRAC](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEIRAC)
TSS: [ZWEITSS](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEITSS)
ACF2: [ZWEIACF](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEIACF)
+|Create Instance Data sets |
**Purpose:**
Create data sets for Zowe's PARMLIB content and non-ZFS extension content for a given Zowe Instance
**Action:**
1) Allocate the PDSE FB80 data set with at least 15 tracks named from Zowe parameter `zowe.setup.dataset.parmlib`
2) Allocate the PDSE FB80 data set with at least 30 tracks named from Zowe parameter `zowe.setup.dataset.authPluginLib`
3) Copy the member `ZWESIP00` from `zowe.setup.dataset.prefix.SZWESAMP` into `zowe.setup.dataset.parmlib` | [ZWEIMVS](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEIMVS) +|APF Authorize privileged content |
**Purpose:**
The majority of Zowe is unprivileged code running in Key 8. Zowe relies on a single component called ZIS to own all of the privileged code logic. The load library for the ZIS component and its extension library must be set as APF authorized and run in Key 4 to use ZIS and components that depend upon it.
**Action:**
1) APF authorize the data sets defined at `zowe.setup.dataset.authLoadlib` and `zowe.setup.dataset.authPluginLib`.
2) Define PPT entries for the members `ZWESIS01` and `ZWESAUX` as Key 4, NOSWAP in the `SCHEDxx` member of the system PARMLIB. | [ZWEIAPF2](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEIAPF2)
+ Grant SAF permissions |
**Purpose:**
The STC accounts for Zowe need permissions for operating servers, and users need permissions for interacting with the servers.
**Action:**
[Set SAF permissions for accounts](https://docs.zowe.org/stable/user-guide/assign-security-permissions-to-users#security-permissions-reference-table) | RACF: [ZWEIRAC](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEIRAC)
TSS: [ZWEITSS](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEITSS)
ACF2: [ZWEIACF](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEIACF)
|(z/OS v2.4 ONLY) Create Zowe SAF Resource Class | On z/OS v2.4, the SAF resource class for Zowe is not included, and must be created. This step is not needed on z/OS v2.5 and later versions. | RACF: [ZWEIRACZ](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEIRACZ)
TSS: [ZWEITSSZ](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEITSSZ)
ACF2: [ZWEIACFZ](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWEIACFZ) - Copy STC JCL to PROCLIB |
**Purpose:**
The job ZWESLSTC runs Zowe's webservers. The job ZWESISTC runs the APF authorized cross-memory server. The job ZWESASTC is started by ZWESISTC on an as-needed basis.
**Action:**
Copy the members ZWESLSTC, ZWESISTC, and ZWESASTC into your desired PROCLIB. If the job names are customized, also modify the YAML values of them in `zowe.setup.security.stcs`. | [ZWEISTC](https://github.com/zowe/zowe-install-packaging/blob/v2.x/staging/files/SZWESAMP/ZWEISTC) + Copy STC JCL to PROCLIB |
**Purpose:**
The job ZWESLSTC runs Zowe's webservers. The job ZWESISTC runs the APF authorized cross-memory server. The job ZWESASTC is started by ZWESISTC on an as-needed basis.
**Action:**
Copy the members ZWESLSTC, ZWESISTC, and ZWESASTC into your desired PROCLIB. If the job names are customized, also modify the YAML values of them in `zowe.setup.security.stcs`. | [ZWEISTC](https://github.com/zowe/zowe-install-packaging/blob/v3.x/staging/files/SZWESAMP/ZWEISTC) -## Keyring Tasks +## Manual JCL Keyring Tasks **Certificate requirements** Ensure that your Zowe keyring has the following elements: @@ -39,7 +164,7 @@ Every intermediate and root Certificate Authority (CA) that Zowe interacts with There are four options for setting up keyrings: Three scenarios presented in the following table include JCL samples where a keyring is created for you. If you already have a keyring, you can configure Zowe to use this keyring by configuring `zowe.yaml` values within `zowe.certificate` according to the following example: -``` +```yaml zowe: certificate: keystore: @@ -64,7 +189,7 @@ zowe: -## (Deprecated) Caching Service VSAM Task +## Manual JCL Caching Service VSAM Task (Deprecated) The Caching Service is a server of Zowe that improves the high availability and fault tolerance of Zowe. It is enabled by default and uses Infinispan for its backing storage by default. @@ -81,7 +206,7 @@ Using VSAM instead of Infinispan is deprecated, but still possible. You can also use JCL samples for removing Zowe configuration: |Action | Sample JCL | |------|-----------| -|Remove Instance Datasets | [ZWERMVS](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWERMVS) +|Remove Instance Data sets | [ZWERMVS](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWERMVS) |Remove SAF Permissions | [ZWENOSEC](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWENOSEC) |Remove Keyring | ACF2:
[ZWENOKRA](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWENOKRA)
RACF:
[ZWENOKRR](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWENOKRR)
TSS:
[ZWENOKRT](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWENOKRT)| -|Remove Caching Service VSAM Dataset | [ZWECSRVS](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWECSRVS) +|Remove Caching Service VSAM Data set | [ZWECSRVS](https://github.com/zowe/zowe-install-packaging/tree/v3.x/master/files/SZWESAMP/ZWECSRVS) diff --git a/docs/user-guide/initialize-zos-system.md b/docs/user-guide/initialize-zos-system.md index cdcba9fe90..34a1bd144c 100644 --- a/docs/user-guide/initialize-zos-system.md +++ b/docs/user-guide/initialize-zos-system.md @@ -6,24 +6,25 @@ Once you complete the installation of the Zowe runtime, begin configuration by i ::: ## About the `zwe init` command - -The `zwe init` command is a combination of the following subcommands. Each subcommand defines a configuration. - + Each subcommand defines a configuration. +The `zwe init` command is a combination of the following subcommands. Except the generate, each subcommand defines a configuration. +- (Optional) **generate** +Used when [configuring with JCL is enabled](./configuring-zowe-via-jcl.md#getting-started-with-zwe-and-jcl). Generates ready to execute JCL samples from YAML configuration values. - **mvs** Copies the data sets provided with Zowe to custom data sets. -- **security** -Creates the user IDs and security manager settings. +- (Deprecated) **vsam** +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. - **apfauth** APF authorizes the LOADLIB containing the modules that need to perform z/OS privileged security calls. +- **security** +Creates the user IDs and security manager settings. - **certificate** Configures Zowe to use TLS certificates. - **stc** Configures the system to launch the Zowe started task. -- (Deprecated) **vsam** -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, and details about the `zwe init security` command, 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, and submit them in the order given above. 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 ::: @@ -31,22 +32,9 @@ We recommend you to run these sub commands one by one to clearly see the output Enter `zwe init --help` to learn more about the command or see the [`zwe init` command reference](../appendix/zwe_server_command_reference/zwe/init/zwe-init-vsam.md) for detailed explanation, examples, and parameters. ::: -## zwe init arguments - -The following `zwe init` arguments can assist you with the initization process: - -- **--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** - This argument allows you to rerun the `zwe init` command repeatedly regardless of whether some data sets are already created. -- **-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** - This argument provides you more execution details than the `--verbose` mode for troubleshooting purposes. - -## Zowe initilization command +## Zowe initialization command -The `zwe init` command runs the subcommands in sequence automatically. If you have the Zowe configuration file preparted and have security administrator privileges, or security and certificates setup was already completed on the system, you can run the following command: +The `zwe init` command runs the subcommands in sequence automatically. If you have the Zowe configuration file prepared and have security administrator privileges, or security and certificates setup was already completed on the system, you can run the following command: ``` zwe init --config /path/to/zowe.yaml diff --git a/docs/user-guide/installandconfig.md b/docs/user-guide/installandconfig.md index 82c70fc25b..4c326689f8 100755 --- a/docs/user-guide/installandconfig.md +++ b/docs/user-guide/installandconfig.md @@ -191,32 +191,6 @@ This data set defined in Zowe configuration contains extra load libraries used b - **`zowe.setup.datasets.loadlib`** This data set defined in Zowe configuration contains load libraries that do not need authorization, such as a version of the configuration manager that can be used within REXX. -### Zowe configuration file (`zowe.yaml`) - -Zowe uses a YAML format configuration. If you store the configuration on USS, this file is usually referred as `zowe.yaml`. - -This configuration file has the following requirements: - -- The Zowe runtime user, usually referred as `ZWESVUSR`, must have read permission to this file. -- If you plan to run Zowe in Sysplex, all Zowe high availability instances must share the same configuration file. As such, this configuration file should be placed in a shared file system (zFS directory) where all LPARs in a Sysplex can access. -- The Zowe configuration file may contain sensitive configuration information so it should be protected against malicious access. - -To create this configuration, you can copy from `example-zowe.yaml` located in Zowe runtime directory. Note that the `zowe.runtimeDirectory` definition in the configuration file should match the Zowe runtime directory mentioned previously. - -To learn more about this Zowe configuration file, see the [Zowe YAML configuration file reference](../appendix/zowe-yaml-configuration.md). - - -:::tip zowe.yaml configuration tips: - -When you execute the `zwe` command, the `--config` or `-c` argument is used to pass the location of a `zowe.yaml` file. - -* To avoid passing `--config` or `-c` to every `zwe` command, you can define `ZWE_CLI_PARAMETER_CONFIG` environment variable points to the location of zowe.yaml. - - For example, after defining `export ZWE_CLI_PARAMETER_CONFIG=/path/to/my/zowe.yaml`, you can simply type `zwe start` instead of the full command `zwe start -c /path/to/my/zowe.yaml`. - -* If you are new to the `example-zowe.yaml` configuration file, you can start with entries that are marked with `COMMONLY_CUSTOMIZED`. It highlights most of the common configurations, such as directories, host and domain name, service ports, certificate setup, and z/OSMF, which are critical for standing a new Zowe instance. -::: - ### Workspace directory The workspace directory is required to launch Zowe. It is automatically created when you start Zowe. More than one workspace directory can be created and used to launch multiple instances of Zowe sharing the same runtime directory. It is not recommended to create workspace directory manually in order to avoid permission conflicts. @@ -237,7 +211,7 @@ Multiple Zowe instances can define different log directories. It is not necessar The log directory should be defined in your Zowe configuration file as `zowe.logDirectory`. -### Keystore directory +### (Optional) Keystore directory Zowe uses certificates to enable transport layer security. The system administrator can choose to use z/OS Keyring or PKCS#12 keystore for certificate storage. A keystore directory is created and used if PKCS#12 keystore is chosen. @@ -255,7 +229,7 @@ Zowe uses certificates to enable transport layer security. The system administra └── localhost.truststore.p12 - Zowe trusted certificate authorities in PKCS#12 format ``` -To generate a keystore directory, you need proper `zowe.setup.certificate` configuration defined in the Zowe configuration file. Execute the server command `zwe init certificate`. To learn more about this command, see the [Reference of zwe init certificate](../appendix/zwe_server_command_reference/zwe/init/zwe-init-certificate.md) in the appendix. +To generate a keystore directory tree, you need to define `zowe.setup.certificate` configuration in the Zowe configuration file. The keystore directory provided to the Zowe configuration must first be created by an administrator. Sub-directories will be created when you run `zwe init certificate` during [certificate configuration steps](https://docs.zowe.org/stable/user-guide/configure-certificates). To learn more about this command, see the [Reference of zwe init certificate](../appendix/zwe_server_command_reference/zwe/init/zwe-init-certificate.md) in the appendix. ### Extension directory @@ -267,6 +241,30 @@ The extension directory should be created by system administrator and defined in Zowe uses [`zwe components install` command](../appendix/zwe_server_command_reference/zwe/components/install/zwe-components-install.md) to install Zowe server extensions. This command creates sub-directories or symbolic links under the extension directory. +### Zowe configuration file (`zowe.yaml`) + +Zowe uses a YAML format configuration. You can choose to store this file in either USS or a data set, and in both cases this will be referred to as `zowe.yaml` throughout the documentation. Our recommendation is to store the `zowe.yaml` file in USS within your workspace directory [as defined above.](#workspace-directory) + +This configuration file has the following requirements: + +- The Zowe runtime user, usually referred as `ZWESVUSR`, must have read permission to this file. +- If you plan to run Zowe in Sysplex, all Zowe high availability instances must share the same configuration file. As such, this configuration file should be placed in a shared file system (zFS directory) where all LPARs in a Sysplex can access. +- The Zowe configuration file may contain sensitive configuration information so it should be protected against malicious access. + +To create this configuration, you can copy from `example-zowe.yaml` located in Zowe runtime directory. Note that the `zowe.runtimeDirectory` definition in the configuration file should match the Zowe runtime directory mentioned previously. + +To learn more about this Zowe configuration file, see the [Zowe YAML configuration file reference](../appendix/zowe-yaml-configuration.md). + + +:::tip zowe.yaml configuration tips: + +When you execute the `zwe` command, the `--config` or `-c` argument is used to pass the location of a `zowe.yaml` file. + +* To avoid passing `--config` or `-c` to every `zwe` command, you can define `ZWE_CLI_PARAMETER_CONFIG` environment variable points to the location of zowe.yaml. + + For example, after defining `export ZWE_CLI_PARAMETER_CONFIG=/path/to/my/zowe.yaml`, you can simply type `zwe start` instead of the full command `zwe start -c /path/to/my/zowe.yaml`. +::: + ## Next step Review and address the specific requirements in the Prepare for Installation section before beginning installation of Zowe server-side components for z/OS. diff --git a/docs/user-guide/systemrequirements-zos.md b/docs/user-guide/systemrequirements-zos.md index fca08c564c..cfa8381c90 100644 --- a/docs/user-guide/systemrequirements-zos.md +++ b/docs/user-guide/systemrequirements-zos.md @@ -31,10 +31,10 @@ Be sure your z/OS system meets the following prerequisites: | Task | Command utilizing SDSF | Alternatives | |-----------|-------------------------------|-------------| - | [Security setup](configuring-security.md) | `zwe init security` | Submit `ZWESECUR` or `ZWENOSEC` manually or use `zwe init security --jcl` | + | [Security setup](configuring-security.md) | `zwe init security` | Use `zwe init security --jcl` as [described here](./configuring-zowe-via-jcl.md#getting-started-with-zwe-and-jcl), or submit `ZWESECUR` or `ZWENOSEC` manually | | [Certificate setup](configure-certificates.md) | `zwe init certificate` | z/OSMF workflow "ZWEKRING", or the JCL samples "ZWEKRING" and those that begin with "ZWEIKR" can be used to create keyrings. | | [Authorize library](../appendix/zwe_server_command_reference/zwe/init/zwe-init-apfauth.md) | `zwe init apfauth` | Products that can issue the MVS `SETPROG APF` command or update `SYS1.PARMLIB(PROGxx)`. See examples in [`SZWESAMP(ZWESIPRG)`](https://github.com/zowe/zowe-install-packaging/blob/v3.x/staging/files/SZWESAMP/ZWESIPRG). | - | [VSAM setup](initialize-vsam-dataset.md) | `zwe init vsam` | Submit `ZWECSRVS` or `ZWECSVSM` manually or use `zwe init vsam --jcl` | + | [VSAM setup](initialize-vsam-dataset.md) | `zwe init vsam` | Use `zwe init vsam --jcl` as [described here](./configuring-zowe-via-jcl.md#getting-started-with-zwe-and-jcl), or submit `ZWECSRVS` or `ZWECSVSM` manually | | [Starting Zowe](start-zowe-zos.md) | `zwe start` | Products that can issue the MVS `START` command upon Zowe's STC such as Sysview or EJES can be used instead. | | [Stopping Zowe](start-zowe-zos.md) | `zwe stop` | Products that can issue the MVS `STOP` command upon Zowe's STC such as Sysview or EJES can be used instead. | diff --git a/docs/user-guide/zwe-init-subcommand-overview.md b/docs/user-guide/zwe-init-subcommand-overview.md index 45d1fabedf..0cbc2b1229 100644 --- a/docs/user-guide/zwe-init-subcommand-overview.md +++ b/docs/user-guide/zwe-init-subcommand-overview.md @@ -21,10 +21,7 @@ Use the `zwe init mvs` command to intialize Zowe custom MVS data sets. :::info Required role: system programmer ::: -During the installation of Zowe, the following three data sets are created and populated with members copied across from the Zowe installation files: -* `SZWEAUTH` -* `SZWESAMP` -* `SZWEEXEC` +During the installation of Zowe, the following [runtime datasets](../appendix/server-datasets.md#runtime-data-sets) are created. The contents of these data sets represent the original files that were provided as part of the Zowe installation and are not meant to be modified. @@ -39,17 +36,11 @@ zowe: prefix: IBMUSER.ZWE parmlib: IBMUSER.ZWE.CUST.PARMLIB jcllib: IBMUSER.ZWE.CUST.JCLLIB - authLoadlib: IBMUSER.ZWE.SZWEAUTH + authLoadlib: IBMUSER.ZWE.CUST.SZWEAUTH authPluginLib: IBMUSER.ZWE.CUST.ZWESAPL ``` -Review the following table for storage requirements for the three data sets: - -Library DDNAME | Member Type | zowe.yaml | Target Volume | Type | Org | RECFM | LRECL | No. of 3390 Trks | No. of DIR Blks ----|---|---|---|---|---|---|---|---|-- -CUST.PARMLIB | PARM Library Members | zowe.setup.dataset.parmlib | ANY | U | PDSE | FB | 80 | 15 | 5 -CUST.JCLLIB | JCL Members | zowe.setup.dataset.jcllib | ANY | U | PDSE | FB | 80 | 15 | 5 -CUST.ZWESAPL | CLIST copy utilities | zowe.setup.dataset.authPluginLib | ANY | U | PDSE | U | 0 | 15 | N/A +Review the [storage requirements](../appendix/server-datasets.md#custom-data-sets) for the datasets. ### Procedure to initialize Zowe custom data sets @@ -68,37 +59,31 @@ The following output is an example of running `zwe init mvs`. ------------------------------------------------------------------------------- >> Initialize Zowe custom data sets -Create data sets if they are not exist +Create data sets if they do not exist Creating IBMUSER.ZWE.CUST.PARMLIB Creating IBMUSER.ZWE.CUST.JCLLIB -Creating IBMUSER.ZWE.SZWEAUTH +Creating IBMUSER.ZWE.CUST.ZWESALL Creating IBMUSER.ZWE.CUST.ZWESAPL -Copy IBMUSER.ZWE.SZWESAMP(ZWESIP00) to USER.ZWE.CUST.PARMLIB(ZWESIP00) -Copy components/zss/LOADLIB/ZWESIS01 to USER.ZWE.SZWEAUTH(ZWESIS01) -Copy components/zss/LOADLIB/ZWESAUX to USER.ZWE.SZWEAUTH(ZWESAUX) -Copy components/launcher/bin/zowe_launcher to USER.ZWE.SZWEAUTH(ZWELNCH) +Copy IBMUSER.ZWE.CUST.SZWESAMP(ZWESIP00) to IBMUSER.ZWE.CUST.PARMLIB(ZWESIP00) +Copy components/zss/LOADLIB/ZWESIS01 to IBMUSER.ZWE.CUST.ZWESALL(ZWESIS01) +Copy components/zss/LOADLIB/ZWESAUX to IBMUSER.ZWE.CUST.ZWESALL(ZWESAUX) +Copy components/zss/LOADLIB/ZWESISDL to IBMUSER.ZWE.CUST.ZWESALL(ZWESISDL) +Copy components/launcher/bin/zowe_launcher to IBMUSER.ZWE.CUST.ZWESALL(ZWELNCH) >> Zowe custom data sets are initialized successfully. -#> ``` 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 following libraries: +* In the `zowe.yaml` file, custom data sets are created that have matching values with the following libraries: * `zowe.setup.dataset.parmlib` * `zowe.setup.dataset.jcllib` + * `zowe.setup.dataset.authLoadlib` * `zowe.setup.dataset.authPluginLib`. * The member `ZWESIP00` is contained in `CUST.PARMLIB`. `JCLLIB` and `ZWESAPL` are empty. -* The PDS `SZWEAUTH` is created. If `SZWEAUTH` already exists, the following error is thrown: - ``` - Error ZWEL0158E: IBMUSER.ZWE.SZWEAUTH already exists - ``` - You can ignore this message, or you can use the `--allow-overwritten` option on the command. For example, `zwe init mvs -c zowe.yaml --allow-overwritten`. - - ## Initializing Zowe security configurations (`zwe init security`) This subcommand creates the user IDs and security manager settings. @@ -150,7 +135,7 @@ Zowe contains load modules that require access to make privileged z/OS security The command `zwe init apfauth` reads the PDS names for the following load libraries from zowe.yaml and performs the APF authority commands. * **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. +Specifies the user custom load library containing the load modules. * **zowe.setup.dataset.authPluginLib** References the load library for ZIS plugins. @@ -158,36 +143,6 @@ For more information about `zwe init apfauth` see: * [Performing APF authorization of load libraries](./apf-authorize-load-library.md). * [`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.ZWE.SZWEAUTH -- Dry-run mode, security setup is NOT performed on the system. - Please apply this operator command manually: - - SETPROG APF,ADD,DSNAME=IBMUSER.ZWE.SZWEAUTH,SMS - -APF authorize IBMUSER.ZWE.CUST.ZWESAPL -- Dry-run mode, security setup is NOT performed on the system. - Please apply this operator command manually: - - SETPROG APF,ADD,DSNAME=IBMUSER.ZWE.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`) @@ -241,16 +196,17 @@ The `zwe init stc` command uses the `CUST.JCL` LIB data sets as a staging area t ------------------------------------------------------------------------------- >> Install Zowe main started task -Modify ZWESLSTC -Modify ZWESISTC -Modify ZWESASTC +Modify ZWESLSTC and save as IBMUSER.ZWE.CUST.JCLLIB(ZWESLSTC) +CONFIG path defined in ZWESLSTC is converted into absolute path and may contain SYSNAME. +Please manually verify if this path works for your environment, especially when you are working in Sysplex environment. +Modify ZWESISTC and save as IBMUSER.ZWE.CUST.JCLLIB(ZWESISTC) +Modify ZWESASTC and save as IBMUSER.ZWE.CUST.JCLLIB(ZWESASTC) Copy IBMUSER.ZWE.CUST.JCLLIB(ZWESLSTC) to USER.PROCLIB(ZWESLSTC) Copy IBMUSER.ZWE.CUST.JCLLIB(ZWESISTC) to USER.PROCLIB(ZWESISTC) Copy IBMUSER.ZWE.CUST.JCLLIB(ZWESASTC) to USER.PROCLIB(ZWESASTC) >> Zowe main started tasks are installed successfully. -#> ``` ## (Deprecated) Creating VSAM caching service datasets (`zwe init vsam`) @@ -262,7 +218,7 @@ Zowe can work in a high availability (HA) configuration where multiple instances :::info Required roles: system programmer ::: -The command `zwe init vsam` uses the template JCL in `SZWESAMP(ZWECSVSM)` to copy the source template member from `zowe.setup.mvs.hlq.SZWESAMP(ZWECVCSM)` and creates a target JCL member in `zowe.setup.mvs.jcllib(ZWECVSCM)` with values extracted from the `zowe.yaml` file. +The command `zwe init vsam` uses the template JCL in `zowe.setup.dataset.prefix` + `.SZWESAMP(ZWECSVSM)`, processes it with values extracted from the `zowe.yaml` file and creates a target JCL member in `zowe.setup.dataset.prefix.jcllib` + `(ZWECVSCM)`. For more information about `zwe init vsam`, see [Creating VSAM caching service datasets](./configure-caching-service-ha.md)