Month: May 2025

Zowe:Configuring a run time instance

You need to configure the z/OS system before you can start Zowe. This work can be done in parallel to configuring the Zowe instance.

Create the run time configuration file

Copy the yaml file from product directory to the instance directory

See detailed instructions

for example

cd /u/tmp/zowep
cp example-zowe.yaml /u/tmp/zowec/zowe.yaml
cd /u/tmp/zowec
oedit zowe.yaml

Basic editing of the zowe.yaml file

The example-zowe.yaml file composes of the definitions used above to set up the MVS definitions, and the configuration of the run time.

Once you have configured the started tasks, APF, security, and security, you do not need the definitions in the run time configuration.

Edit the zowe.yaml file, and delete from the start of the file down to just before

# >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
# **COMMONLY_CUSTOMIZED**

Insert

zowe:

starting in column 1 at the start of the file.

Run time parameters

The run time directory

This is the directory with the product code. 

   runtimeDirectory: /u/colin/zowep

Note. The runtime… is indented by two characters. You will have used this, either in your PATH statement, or in /u/colin/zowep/bin/zwe above.

Where to store runtime logs.

This is machine and instance dependant.

You need to decide which directory is used. Should it be available across all systems, or only available on one system, and if the LPAR and Zowe instance name is part of the directory structure. See High level directory structures.

The default value of logDirectory: is /global/zowe/logs.

Where to place the workspace directory.

This directory is used to store Zowe internal configuration information. See the discussion above in Where to store runtime logs.

The default value of workspaceDirectory: is /global/zowe/workspace

Where extensions are installed

See Where to store extensions, for a discussion about wanting to shared extension files between instances.

The default value of extensionDirectory: is

/global/zowe/extensions

What job names to use?

You can specify

job: 
  # Zowe JES job name 
  # name: ZWE1SV 
  # Prefix of component address space 
  prefix: ZWE1

When the Java instances are started, the BPXAS address spaces are given names like ZWE1GW. You can use this in the WLM definitions.

Set two variables to default values

Role Based Access Control(rbac) is an advanced topic.

cookieIdentifier is used when there are multiple Zowe instances. You can specify a value so each instance gets its own cookies.

 rbacProfileIdentifier: "1"                                                  
 cookieIdentifier: "1"

Initially set these values to “1” and review them when you have multiple Zowe instances.

Quit on error or give warning and continue

You can specify

  configmgr:
    # STRICT=quit on any error, including missing schema
    # COMPONENT-COMPAT=if component missing schema, skip it with warning instead of quit
    validation: "STRICT"

Specify the TCP/IP domain name

  externalDomains: 
    # this should be the domain name to access Zowe APIML Gateway 
    - sample-domain.com

Specify the TCP/IP port needed for the gateway

  externalPort: 7554

Configure the TLS definitions

 network: 
   server: 
     tls: 
       attls: false 
       # TLS settings only apply when attls=false 
       # Else you must use AT-TLS configuration for TLS customization. 
       minTls: "TLSv1.2" 
       maxTls: "TLSv1.3" 
   client: 
     tls: 
       attls: false

Depending on whether you use TLS 1.2 and/or TLS 1.2, you might want to start with minTls: Tlsv1.2 and migrate to TLS 1.3 later.

Which messages go to syslog?

You can configure which messages are written to the syslog, in addition to the internal message logs. The supplied list is 

  sysMessages: 
  #   # Zowe starting 
    - "ZWEL0021I" 
  #   # Zowe started 
    - "ZWEL0018I" 
    - "ZWEL0006I" 
  #   # Zowe ready to use 
    - "ZWES1601I" 
  #   # Zowe stopping 
    - "ZWEL0008I" 
  #   # Zowe stopped 
    - "ZWEL0022I" 
  #   # Zowe components starting 
    - "ZWEL0001I" 
  #   # Zowe components stopped 
    - "ZWEL0002I" 
  #   # API ML components ready 
    - "ZWEAM000I" 
  #   # App server ready 
    - "ZWED0031I" 
  #   # ZSS ready 
    - "ZWES1013I"

You may want to configure your automation to respond to these messages, so your status displays can show the status of the Zowe instance.

Enable debug at startup

  launchScript: 
    logLevel: "warn" 
    onComponentConfigureFail: "warn"

If you have problems starting Zowe, set this to debug.

Once Zowe has been configured and is working satisfactory, you can reset this to warn.

Specify the names of the certificate and keyrings

                                                                                   
  certificate: 
      keystore: 
        type: JCERACFKS 
        file: safkeyring:////IZUSVR/CCPKeyring.IZUDFLT 
        alias: CONN2.IZUDFLT 
      truststore: 
        type: JCERACFKS 
        file: safkeyring:////IZUSVR/CCPKeyring.IZUDFLT 
                                                                                       
  verifyCertificates: STRICT

The directories for Java and NodeJS

java: 
  home: /usr/lpp/java/J17.0_64 
                                                                             
                                                                             
node: 
   home: /usr/lpp/IBM/cnj/IBM/node-v20.11.0-os390-s390x-202402131732

Specify some z/OSMF value

You can use z/OSMF for authentication. You need to specify some values even though you are not initially using z/OSMF.

zOSMF: 
  host: 127.0.0.1
  port: 10443 
  applId: IZUDFLT

Define the components

The gateway component

When setting up Zowe for the first time, define just one component, and get that working. Once it is working you can add more components

components: 
                                                        
  gateway: 
    enabled: true  
    port: 7554 
    debug: true 
    apiml: 
      security: 
        auth: 
          provider: saf 
#         zosmf: 
#           jwtAutoconfiguration: jwt 
#           serviceId: ibmzosmf 
        authorization: 
          endpoint: 
            enabled: false 
          provider: "native" 
        x509: 
          enabled: false

Initially set these to enabled: false

  zaas: 
    enabled: false          # was true 
    port: 7558 
    debug: false 
  
  api-catalog: 
    enabled: false  # was true 
    port: 7552 
    debug: true 
                                                                 
  discovery: 
    enabled: false # was true 
    port: 7553 
    debug: true

  app-server: 
    enabled: false 
    port: 7556 
    debug: true 

  caching-service:
     enabled: false
     port: 7555
       storage:
         evictionStrategy: reject
         mode: imMemory
         size: 10000

For zss set enabled: true so it starts when Zowe starts.

  zss: 
    enabled: true
    port: 7557 
    crossMemoryServerName: ZWESIS_STD 
    agent: 
      jwt: 
        fallback: true 
      64bit: true 
#     https: 
#       trace: true

Now what?

The Zowe started task procedure needs to point to this configuration file.

Zowe: What is Zowe

At one level Zowe allows people running on their works stations to access z/OS without having to logon to TSO and use ISPF. This can be done using

  • A browser
  • A scriptable command level interface(s)
  • Plug in to VSCode, so you can do all your work using the IDE.
  • You own code using a REST API using URLs and data in JSON format.

What is unique about Zowe?

There are other products which provide similar function. For example z/OSMF (z/OS Management Facility) provides many of the same facilities. Zowe uses z/OSMF for a lot of the function.

I’ll give a bit of history to show how Zowe and z/OSMF fit in today’s environment.

The 1970’s

In the the 1970’s a client machine would connect to z/OS quite likely using a proprietary interface. There may be one or just a few (for availability) back end servers . A typical client might connect to the server in the morning, and stay connected all day until the client machine was shutdown. The cost of using the networks was high, and a typical transaction had several flows to and from the server, sending updates (rather than the whole transaction data – see below).

One of the problems with this model is if you start another server mid-morning, it may get very few connections because the client connected to the server first thing, and might only go to the new server if they had to restart.

Another problem is that the client only signed on once a day, and if a userid was revoked it would still be in use till the client shut down.

Both of these problems can be solved by having the clients periodically disconnect at the end of a transaction and reconnect.

Today…

The architecture has matured. The web browser is used as a front end for much of the transactions. A typical request is now a url like

https://bigshop.co.uk:5555/sales?part=123456,name=ColinPaice


Where

  • https: is the protocol, another protocol could be ftp
  • bigshop.co.uk: is the IP address (or the name which maps to an IP address)
  • 5555: the port on the server
  • sales: this is the transaction
  • ?: splits the transaction from the data
  • part=123456,name=ColinPaice: this is the data passed to the transaction.

When this request flows to the server there may be a software router in z/OS which says “if this is a new session request – then send it to the lightest used server”. This gives load balancing. If you issue the same request multiple times it may go to different servers each time.

The request gets to a server machine. Several instances of an application can be running listening on the port 5555. Again this provides workload balancing.

One shot request

A request can be one-shot – start a session, authenticate, do something, get a response back – end. This provides a highly available scalable solution. You can take servers in and out of commission and work will execute.

Conversation request

A session can be long lived, where there are many flows within a session. For example list all data set, display this member etc. This does: start a session, authenticate, have a conversation end.

When the server responds to the request it sends back the IP address for future traffic in the session, and the session specific port. When the client sends data within the session, it goes to this partner session.

Authentication

Authentication can be expensive. For example using TLS to provide secure network flows, requires several network flows. Using a certificate or userid and password can be expensive. TLS has a Session resumption or fast reconnect. If you disconnect and reconnect again the client can send a token, the server can validate it, and if it is valid bypass some of the set up.

To reduce the costs at the application to application level, you can use an authentication token. Once you have authenticated, you are given an encrypted token. This token contains your userid and other information, and is valid for a time period ranging from minutes to hours. If the token expires you have to re-authenticate to get a new token. This token may be valid across server instances on one machine, and may be valid on servers on different systems.

How do you issue a request?

You can write your own program to establish a TCP/IP session to the server and send and receive data. There are several tools to help you, including cURL, openssl client, Python, Java and the Zowe client.

Many services are REST services, where the server has no saved information, and all requried information is passed in the request data.

For example using cURL to logon, using a certificate, and not using a userid/password

curl --cookie-jar zowe.cookie.jar --cookie zowe.cookie.jar --key ./colinpaice.key.pem  --cert ./colinpaice.pem:password   --cacert ./doczosca.pem -c - -X POST https://10.1.1.2:7554/gateway/api/v1/auth/login

Where

  • –cookie-jar … is where tokens (http tokens) are saved across invocations.
  • –key…. contains the user’s private key, used to encrypt data
  • –-cert … is the public certificate sent to the server as part of the TLS handshake. It is used to decrypt ( and so validate the encrypted data sent to the server)
  • -cacert …. is the TLS certificate used to validate the TLS cerificate sent from the server
  • -X POST which http protocol to use
  • https://10.1.1.2:7554/gateway/api/v1/auth/login
    • It is http using tls ( hence the https)
    • The IP address is 10.1.1.2
    • The port is 7554
    • The application within the server is gateway/api/v1/auth/login.

The back end looks up the id from the certificate and finds the associated userid. This look up can be for a specific distinguish name, or part of the distinguished name, such as all those with o=bigbank.co.uk in the DN.

Curl has options so you can have the network traffic displayed (in clear text) so you can validate what certificates etc are being used.

I use curl to check out the backend before using Zowe.

You can specify a userid and password using the cURL options “–basic –user colin:passw0rd”.

TLS can validate the certificate, and then use the specified userid and password for authentication.

How to define an application

You can configure the back end server for Zowe and z/OSMF in different ways

So what does Zowe do?

The Zowe Command Level Interface implements the REST API and hides some of the complexity, of what headers are needed. You can provide a system wide configuration file containing the default parameters for all users, a team/project wide for the defaults specific to a team, and a person file of parameters just for you.

Zowe has been designed to work with The VSCode Interactive Development Environment, and so you can edit files on your workstation, and have them copied back to z/OS when you save the file. You can look at spool files, and issue operator commands. All this in a familiar development environment.

z/OS curl headers not always working.

I had problems using cURL trying to get to a back end server (z/OSMF). Once it did work, I realised it should not have worked – because I had not defined a security profile!

My basic bash script was 

set -x 
trace=" " 
ca="--cacert /u/colin/ssl/zosmfca.pem" 
key="--cert  key.pem:12345678              " 
insecure="--insecure" 
cert=" " 
header='-H "X-CSRF-ZOSMF-HEADER: Dummy "' 
userid="--basic --user colin2:password" 
url="https://127.0.0.1:10443/zosmf/rest/mvssubs"

If I hard coded the header statement it worked

curl -v  -H "X-CSRF-ZOSMF-HEADER: dummy" $trace $cert $key $insecure $userid $ca  $url

If I used the bash variable in $header it did not work, even though it looked as if was identical to the case above.

curl  -v  -H  $header $trace $cert $key $insecure  $userid $ca  $url

{ “errorID”:”IZUG846W”,”errorMsg”:”IZUG846W: An HTTP request for a z/OSMF REST service was received from a remote site. The request was rejected, however, because the remote site “” is not permitted to z/OSMF server “IZUSVR” on target system “127.0.0.1:10443″ .”}

If I put the parameter in a config file (curl.config below) it worked

-H "X-CSRF-ZOSMF-HEADER: Dummy"

and I used 

curl -v --config ./curl.config $trace $cert $key $insecure $userid $ca $url

I think it is all to do with an interaction between curl, bash and double quotes.

It worked – when it should not have worked!

The documentation says you need a security profile set up see Enabling cross-origin resource sharing (CORS) for REST services.

On my system, there was no profile IZUDFLT.REST…. so I do not understand how it works, as the documentation implies I need an allow list!

Using SlickEdit to edit your source on z/OS and submit JCL to process it

SlickEdit is an IDE (Interactive Development Environment). As well as editing code, for some programs you can execute and debug the programs. At the top of the display is a tool bar which has “…Build Debug…”. You can use these to send commands to z/OS and retrieve the output. This includes running commands in the Unix shell, for example the make command, and running commands which submit JCL and retrieve the output.

Configuring SlickEdit

Project-> Project Properties allows you to configure the tool bar. Under Tools, Tool name: Build I have

The key fields are the “Command Line”. This is the command to issue… the command has the following

  • ssh issue this command
  • -i /home/colinpaice/.ssh/id_rsa.pub When setting up password-less logon, the SSH keys are stored here.
  • colin@10.1.1.2 the userid and system where the command is to execute
  • ./d.rexx parm the command to execute. See Submitting jobs from Rexx in Unix Services.
  • %n pass the name of the file being edited

Save workspace files save the current data, and uploads it before issuing the build command.

Clear output window. If this is unticked, the build window grows in size, and shows your history. If this is ticked, you just see the output from the active command.

Having configured the Build, If you click on Build on the tool bar it gives you

  • Compile shift + F10
  • Build Ctrl+M
  • Rebuild
  • Debug
  • Add new build tool
  • …
  • Build automatically on save

Having edited your source, you can use Ctrl+M to save the file being edited (and upload it to z/OS), submit the command to z/OS, and watch the output returned.

You can choose where the output of the build command is displayed, for example in the build window or “terminal 1”. You can drag this window away from the main SlickEdit window, so keep an eye on it as you edit other files.

Getting it working

See