Zowe: How to save connection parameters: zowe CLI client configuration files

A Zowe client needs information to be able to invoke a service on Zowe on z/OS. Typically these are

• host address
• the host port
• the service
• the client public key .pem file
• the client private key .pem file
• whether to not allow self signed certificates sent from the host
• the file containing the CA from the host servers.

These options can be given on the zowe cli command, or can be stored in profile files.

You can have multiple profiles, for example, tso, ssh, z/OSMF, production z/OSMF and test z/OSMF.

The above information may be different for different Zowe server instances- such as development, test and production, and for different applications within a Zowe instance.

Some configuration files are stored in the directory pointed to by the environment variable ZOWE_CLI_HOME, on Linux this defaults to ~/.zowe. These files are available where ever your working directory is. You can also have a configuration file in your working directory so is “application specific”.

Zowe supports a hierarchy of configuration files.

• zowe.config.json within the current directory. If you change directory you will not use it.
• zowe.config.user.json , the global user file in the ZOWE_CLI_HOME environment variable ( or it might default to ~/.zowe ). This is used for any user specific options (if any)
• zowe.config.json the global file in the ZOWE_CLI_HOME environment variable ( or it might default to ~/.zowe ). This is used for project wide options.

The Zowe CLI command will start at the top of the hierarchy and go down until it finds the attributes. If it cannot find an attribute it may have a default.

Within the configuration file are different sections, for example

• a base section with common parameters,
• ftp, with specific parameters such as the FTP port number,
• zOSMF, with with specific parameters such as the z/OSMF port number

You can edit the files manually, or use the Zowe config command to make changes.

Sigh

To specify a Certificate Authority(CA) certificate to a zowe cli command, you have to use an environment variable, for example

export NODE_EXTRA_CA_CERTS=/home/colinpaice/ssl/ssl2/doczosca.pem

You need to allow for this when writing your scripts, because different backend servers may have different CA certificates.

See here.

Getting started

Once you are familiar with Zowe and have a better idea of your Zowe configuration, you can develop the various configuration files; what information is user specific, what information is project specific, and what information is Zowe instance specific. Some files are stored in the direction in the ZOWE_CLI_HOME environment variable which defaults to ~/.zowe (on Linux).

If you may have more than one Zowe instance, you may decide NOT to use ~/.zowe, but have directories like ~/.zoweproduction and ~/.zowetest. This means you have to explicitly specify the location.

Get started by creating zowe.config.json in your working directory. See below, or use cut and paste from here, step 3. If you use an IDE such as slickedit or vscode, these have syntax assist, and can highlight errors as you type.

This is a good blog post on initial configuration. But does not cover use of certificates.

The Zowe config command

You can use the zowe config command to create and update the configuration files. The command has options including

This page has a good description of the options.

• –dry-run : display the changes, but do not apply the changes
• –edit and –editor name : this opens the file in the specified editor.

Create a zowe.config.json in the current directory

The command

zowe config init

will create a file zowe.config.json in the current directory.

I created a minimum (hand crafted) file to illustrate how the zowe config commands work.

{
    "$schema": "./zowe.schema.json",
    "profiles": {
        "zosmfcp": {
            "type": "zosmf",
            "properties": {
                "port": 443
            },
            "secure": []
        },
    
        "project_base": {
            "type": "base",
            "properties": {
                "host": "10.1.1.2",
                "rejectUnauthorized": true
            },
            "secure": [
                "user",
                "password"
            ]
        }
    },
    "defaults": {
        "zosmf": "zosmfcp",
        "base": "project_base"
    },
    "autoStore": true
}

Key elements of this file

• “defaults”:
  • zosmf : For a z/OSMF request,if --base-profile is not specified, use the referenced profile – zosmfcp.
  • common parameters are defined in the base: profile -> project_base
• “profiles”: There are two profiles defined
  • zosmfcp with the zosmf specific parameters
  • project_base with the common parameters.

When a zowe command is used, the parameter –base-profile can specify which profile to use.

Commands to display and set profile information

• list the file names zowe config list –locations –root
• list the file names and their contents zowe config list –locations
• change a parameter in the file in the current directory
• add a profile (and content) to the the file in the current directory
• set a parameter in the file in the user configuration file
• set a parameter in the file in the global configuration file
• display profiles

My working directory is /home/colinpaice/ssl/ssl2/ .

zowe config list –locations –root

This lists the only the file names used by Zowe CLI.

/home/colinpaice/ssl/ssl2/zowe.config.json
/home/colinpaice/.zowe/zowe.config.json

zowe config list –locations

This shows the file names and their contents

/home/colinpaice/ssl/ssl2/zowe.config.json: 
  $schema:   ./zowe.schema.json
  profiles: 
    zosmf: 
      type:       zosmf
      properties: 
        port: 10443
      secure: 
        (empty array)
    project_base: 
     ...
/home/colinpaice/.zowe/zowe.config.json: 
  $schema:   ./zowe.schema.json
  profiles: 
    zosmf: 
      type:       zosmf
      properties: 
        port: 10443
      secure: 
        (empty array)
    tso: 
      type:       tso
....
   global_base: 
      type:       base
      properties: 
        host:               10.1.1.2
        rejectUnauthorized: true
        user:               (secure value)
        password:           (secure value)
      secure: 
        - user
        - password
  defaults: 
    zosmf: zosmf
    tso:   tso
    ssh:   ssh
    base:  global_base
  autoStore: true

Change a parameter in the file in the current directory

zowe config set “profiles.zosmf.properties.port “30443”

Change/Add a profile (and content) to the the file in the current directory

zowe config set “profiles.zosmf2.properties.port” “40443”

If the profile zosmf2 did not exist before, it will create it, and add the property port

{
    "$schema": "./zowe.schema.json",
    "profiles": {
         ...
        "zosmf2": {
            "properties": {
                "port": 40443
            }
        }
    },
    ...
}

Set a parameter in the file in the user configuration file

zowe config set “profiles.zosmf2.properties.port” “40443” –user-config

set a parameter in the file in the global configuration file

zowe config set “profiles.zosmf2.properties.port” “50443” –global-config

Example of using the set commands

zowe config set “profiles.zosmf2.properties.port” “50443” –global-config
zowe config set “profiles.zosmf2.properties.port” “4444” –user-config
zowe config set “profiles.zosmf2.properties.port” “1111”

• file zowe.config.user.json has zosmf2.properties.port:4444
• file zowe.config.json: has zosmf2.properties.port: 1111
• file ~/.zowe/zowe.config.json: has zosmf2.properties.port: 50443

Using the list commands, and displaying only the above fields I have

zowe config list gives

profiles: 
  ...
  zosmf2: 
    properties: 
      port: 4444

zowe config list –locations gives

/home/colinpaice/ssl/ssl2/zowe.config.user.json: 
  profiles: 
    zosmf2: 
      properties: 
        port: 4444
  defaults: 
/home/colinpaice/ssl/ssl2/zowe.config.json:
  profiles:
    ...
    zosmf2: 
      properties: 
        port: 1111
    ... 
/home/colinpaice/.zowe/zowe.config.json: 
  $schema:   ./zowe.schema.json
  profiles: 
   ...
   zosmf2: 
      properties: 
        port: 50443

So we can see the profile /home/colinpaice/ssl/ssl2/zowe.config.user.json: provided the port value 444.

If I use –base-profile zosmf2, the port used will be 4444.

If I add

zowe config set “profiles.zosmf2.properties.ca” “MYCA”

This create property zosmf2:properties:ca:”MYCA” in file zowe.config.json.

zowe config list gives

profiles:
  zosmf2: 
    properties: 
      port: 4444
      ca:   MYCA

so we can see what is being used.

If I use zowe config list –locations I can see the definition is in /home/colinpaice/ssl/ssl2/zowe.config.json

display profiles

zowe config profiles gave

zosmf
tso
ssh
global_base
zosmf2

What are the valid options?

If you used the zowe config init command, then this generated a schema file.

For zosmf this schema has

• “host”: “The z/OSMF server host name.”
• “port”: “default”: 443
• “user”: “Mainframe (z/OSMF) user name, which can be the same as your TSO login.”
• “password”: “Mainframe (z/OSMF) password, which can be the same as your TSO password.”
• “rejectUnauthorized”:”Reject self-signed certificates.”, “default”: true
• “certFile”: “The file path to a certificate file to use for authentication” “certKeyFile”: “The file path to a certificate key file to use for authentication”
• “basePath”: “The base path for your API mediation layer instance. Specify this option to prepend the base path to all z/OSMF resources when making REST requests. Do not specify this option if you are not using an API mediation layer.”
• “protocol”: “The protocol used (HTTP or HTTPS)” “default”: “https”, “http”, “https”
• “encoding”: “The encoding for download and upload of z/OS data set and USS files. The default encoding if not specified is IBM-1047.”
• “responseTimeout”: “The maximum amount of time in seconds the z/OSMF Files TSO servlet should run before returning a response. Any request exceeding this amount of time will be terminated and return an error. Allowed values: 5 – 600”

The CA certificate to use is specified by an environment variable, and is not a parameter in the profiles.