Issue with docs.zowe.org/stable/user-guide/configuring-zowe-via-jcl

[colinpaicemq]

Description

Problems with IBMUSER.ZWEV3A.SZWESAMP(ZWEGENER)

I get

ISPSTART CMD(%ZWEGEN00 nogenerate noverbose )
ISPF system data set allocation error - press Enter to continue.
Log file allocation error - ISPF will operate without a log data set.
Data set 'COLIN.S0W1.SPFLOG1.LIST' in use by another user, try later.

You need

//ISPLIST DD SYSOUT=,
// DCB=(LRECL=121,BLKSIZE=1210,RECFM=FBA)
//ISPLOG DD SYSOUT=,
// DCB=(LRECL=125,BLKSIZE=129,RECFM=VA)

---

I also got message

CEE3608I The following messages pertain to the invocation command run-time options. ...
there were no following messages... what am I meant to do ?

---

I specified

//MYCONFIG DD *,DLM=$$
FILE /u/tmp/zowec/example1.yaml
FILE /u/tmp/zowec/example2.yaml
$$

example1 had
zowe:

setup:
# MVS data set related configurations
dataset:
# COMMONLY_CUSTOMIZED
# where Zowe MVS data sets will be installed
prefix: IBMUSER.ZWEV3A
# COMMONLY_CUSTOMIZED
# PROCLIB where Zowe STCs will be copied over
proclib: USER.PROCLIB
# COMMONLY_CUSTOMIZED
# Zowe PARMLIB
parmlib: IBMUSER.ZWEV3A.CUST.PARMLIB
# Holds Zowe PARMLIB members for plugins
parmlibMembers:
# For ZIS plugins
zis: ZWESIP00
# COMMONLY_CUSTOMIZED
# JCL library where Zowe will store temporary JCLs during initialization
jcllib: IBMUSER.ZWEV3A.CUST.JCLLIB
# Utilities for use by Zowe and extensions
loadlib: IBMUSER.ZWEV3A.SZWELOAD
# APF authorized LOADLIB for Zowe
authLoadlib: IBMUSER.ZWEV3A.SZWEAUTH
# COMMONLY_CUSTOMIZED
# APF authorized

and example2 had

  security: 
    product: RACF 
    groups: 
      admin: ZWEADMIN 
      stc: ZWEADMIN 
      sysProg: ZWEADMIN 
    users: 
      zowe: ZWESVUSR 
      zis: ZWESIUSR 
    stcs: 
      zowe: ZWESLSTC 
      zis: ZWESISTC 
      aux: ZWESASTC 

I got (quite rightly)

validateStatus=4
Validity Exceptions(s) with object at
unspecified additional property not allowed: 'security' at '/security'
******************************** BOTTOM OF DATA **********************************

I need some more words to explain what multiple files look like

I tried example2 with

zowe:
# Security related configurations. This setup is optional.
security:
# security product name. Can be RACF, ACF2 or TSS
product: RACF
# security group name
groups:

I eventually found I needed

zowe:
# Security related configurations. This setup is optional.
setup:
security:
# security product name. Can be RACF, ACF2 or TSS
product: RACF
# security group name

So all of the steps in the heirrchy

you need to say that if the same definition is in multiple files the first/last take precedence

Pages to Update

Screenshots

Expected behavior

Additional context

[1000TurquoisePogs]

Yes, users who make significant customizations of YAML need to have an understanding of YAML syntax.
YAML is an indentation sensitive format, if you omit parts, you get a whole different meaning.

There has been prior discussion on how much Zowe documentation should to do explain concepts of other topics. We do have this https://docs.zowe.org/stable/appendix/zowe-yaml-configuration
But it is not put in bold up top anywhere that people should not make significant changes without first becoming familiar with YAML.

This page documents how you can chain together YAML and how they are merged
https://docs.zowe.org/stable/user-guide/configmgr-using
But, it is hidden in "advanced configuration"

This is because knowing any of this is not necessary to get Zowe working and would further complicate simple setups.

I agreed with a prior discussion that our examples should simply come in various small YAMLs and that'd be a great starting point, but I don't think telling people how to make their own is something we should be putting up front. We know from experience that YAML is a powerful tool that can easily be broken, so, I think it's proper to keep that page in the "advanced" section.

[colinpaicemq]

it is a dilemma between one big yaml file and several smaller ones.

I found the single yaml file very cumbersome to use. keyrings are mentioned in several places --- which do I need to update

I didn't want Zowe to generate any certificates for me... so what do I need to specify?

One of the first things I did when trying to configure the yaml for the first time was to take a copy of the file
and remove all comment lines starting in cols 1-5

I could then see just two pages of information - that was much clearer for me

I would be much happier having small sections - and so ignore all of the sections on defining certicates.... but this sounds like a lot of work.

---

I think all you need to do to get over my current problem is
have words like

Each file must be syntactically correct and self contained.
For example

file1

zowe:
  setup:
    security:

file2

zowe: 
  runtimeDirectory: "..." 
  logDirectory: ..._ 

[1000TurquoisePogs]

Regarding splitting YAMLs, consider this:

When setting up Zowe, example Zowe YAML configuration files are provided for your convenience.
Each file servers a particular purpose, though all properties are part of the same YAML namespace, as Zowe YAML can be combined or split according to operations which support the Config Manager
In addition to the files below, the file defaults.yaml always applies and can be referred to for omitting unneeded customization or restoring default behaviors.

Filename	Purpose	Associated commands and references
example-datasets.yaml	Custom Dataset Setup	Command 'zwe init mvs' Job ZWEIMVS
example-proc.yaml	Proclib setup	Command 'zwe init stc' Job ZWEISTC Copying STC into Proclib
example-security.yaml	Security setup	Command 'zwe init security' Job ZWEIRAC Job ZWEITSS Job ZWEIACF

and on and on. that's not an exhaustive list nor exhaustive list of associated commands and references

Now as you read these examples, you may see why this is both a step forward and backward:

• some operations need the same data, causing them to be duplicated across files when split
• multiple yaml requires responsibility for people to actually use them. there's been enough incidents of the documentation clearly stating something, only for people to not read the documentation
• the notion of splitting & merging yaml is too much information likely, and causes problems in that not all commands support it, thus people may use it where it cannot be used.

example-datasets.yaml

zowe:
  setup:
    # These properties are used by the unix command "zwe init mvs" or the job "ZWEIMVS"
    dataset:
      # where Zowe MVS data sets were installed
      prefix: IBMUSER.ZWEV3
      # Zowe PARMLIB
      parmlib: IBMUSER.ZWEV3.CUST.PARMLIB
      # JCL library where Zowe will store temporary JCLs during initialization
      jcllib: IBMUSER.ZWEV3.CUST.JCLLIB
      # APF authorized LOADLIB for Zowe
      authLoadlib: IBMUSER.ZWEV3.SZWEAUTH
      # APF authorized LOADLIB for Zowe ZIS Plugins
      authPluginLib: IBMUSER.ZWEV3.CUST.ZWESAPL

example-proc.yaml

zowe:
  setup:
    # These properties are used by the unix command "zwe init stc" or the job "ZWEISTC"
    dataset:
      # where Zowe MVS data sets were installed
      prefix: IBMUSER.ZWEV3
      # PROCLIB where Zowe STCs will be copied over
      proclib: USER.PROCLIB
    security:
      stcs:
        # STC name of Zowe main service
        zowe: ZWESLSTC
        # STC name of Zowe ZIS
        zis: ZWESISTC
        # STC name of Zowe ZIS Auxiliary Server
        aux: ZWESASTC

example-security.yaml

zowe:
  setup:
    # These properties are used by the unix command "zwe init security"
    # or the jobs "ZWEIRAC", "ZWEITSS", and "ZWEIACF" depending upon your security product.
    security:
      # security product name. Can be RACF, ACF2 or TSS
      product: RACF
      # security group name
      groups:
        # Zowe admin user group
        admin: ZWEADMIN
        # Zowe STC group
        stc: ZWEADMIN
        # Zowe SysProg group
        sysProg: ZWEADMIN
      # security user name
      users:
        # Zowe runtime user name of main service
        zowe: ZWESVUSR
        # Zowe runtime user name of ZIS
        zis: ZWESIUSR
      # STC names
      stcs:
        # STC name of Zowe main service
        zowe: ZWESLSTC
        # STC name of Zowe ZIS
        zis: ZWESISTC
        # STC name of Zowe ZIS Auxiliary Server
        aux: ZWESASTC

[colinpaicemq]

I raised a doc comment ( but I cannot find it) saying the ZWEIRAC file should be split into

system wide stuff

userid stuff

Instance stuff.

One reason for this is that you do not just want to apply the system wide stuff without careful testing.
I've just hit this. The Zowe definitions defined the SERVER class. Now my z/OSMF fails to start because the z/OSMF definitions were wrong. It will take me 10 mins to fix - but this would have been a sev 1 outage in a customer production image.