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.jsonthe 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-profileis not specified, use the referenced profile – zosmfcp. - common parameters are defined in the base: profile -> project_base
- zosmf : For a z/OSMF request,if
- “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.
ColinPaice 