Creating and configuring the Zowe instance directory
Creating and configuring the Zowe instance directory
The Zowe instance directory or <INSTANCE_DIRECTORY>
contains configuration data required to launch a Zowe runtime. This includes port numbers, location of dependent runtimes such as Java, Node, z/OSMF, as well as log files. When Zowe is started, configuration data will be read from files in the instance directory and logs will be written to files in the instance directory.
Note: The creation of an instance directory will set default values for users who want to run all Zowe z/OS components. If you are using Docker, you must make a small configuration change to disable the components on z/OS that will instead run in Docker.
#
IntroductionThe purpose of the instance directory is to hold information in the z/OS File System (zFS) that is created (such as log files) or modified (such as preferences) or configured (such as port numbers) away from the zFS runtime directory for Zowe. This allows the runtime directory to be read-only and to be replaced when a new Zowe release is installed, with customizations being preserved in the instance directory.
Multiple instance directories can be created and used to launch independent Zowe runtimes from the same Zowe runtime directory.
The Zowe instance directory contains a file instance.env
that stores the Zowe configuration data. The data is read each time Zowe is started. You can modify instance.env
to configure the Zowe runtime. See Updating the instance.env configuration file for more information.
Alternatively, from v1.22.0 release, you can use a YAML format configuration file zowe.yaml
instead of instance.env
to configure the Zowe runtime. See Updating the zowe.yaml configuration file for more information.
The instance directory <INSTANCE_DIRECTORY>/bin
contains other key scripts as follows:
zowe-start.sh
is used to start the Zowe runtime by launching theZWESVSTC
started task.zowe-stop.sh
is used to stop the Zowe runtime by terminating theZWESVSTC
started task.zowe-support.sh
can be used to capture diagnostics around the Zowe runtime for troubleshooting and off-line problem determination, see Capturing diagnostics to assist problem determination.
High availability considerations:
- If you plan to run Zowe in a Sysplex for high availability, the instance directory should be placed in a shared USS file system. This way, all Zowe instances within the Sysplex can read and write to the same instance directory.
zowe.yaml
is required if you want to start Zowe in high availability mode.
#
PrerequisitesBefore creating an instance directory, ensure that you have created a keystore directory that contains the Zowe certificate. See Creating Zowe certificates for instructions. Also, ensure that you have already configured the z/OS environment. See Configuring the z/OS system for Zowe for instructions.
#
Creating an instance directoryTo create an instance directory, use the zowe-configure-instance.sh
script.
Navigate to the Zowe runtime directory <RUNTIME_DIR>
and execute the following commands:
<RUNTIME_DIR>/bin/zowe-configure-instance.sh -c <PATH_TO_INSTANCE_DIR>
If you have an instance directory that is created from a previous release of Zowe 1.8 or later and are installing a newer release of Zowe, then you should run zowe-configure-instance.sh -c <PATH_TO_INSTANCE_DIR>
pointing to the existing instance directory to have it updated with any new values. The release documentation for each new release will specify when this is required, and the file manifest.json
within each instance directory contains information for which Zowe release it was created from.
In order to allow the ZWESVSTC
started task to have permission to access the contents of the <INSTANCE_DIR>
the zowe-configure-instance.sh
script sets the group ownership of the top level directory and its child to be ZWEADMIN
. If a different group is used for the ZWESVSTC
started task you can specify this with the optional -g
argument, for example.
<RUNTIME_DIR>/bin/zowe-configure-instance.sh -c <PATH_TO_INSTANCE_DIR> -g <GROUP>
Watch the following video that shows how to create an instance.env
file that is used to launch Zowe with default parameters and a USS keystore containing a self-signed TLS certificate.
#
Updating the instance.env configuration fileTo operate Zowe, a number of zFS folders need to be located for prerequisites on the platform. Default values are selected when you run zowe-configure-instance.sh
. You might want to modify the values.
Contents in this section
- Zowe prerequisites
- Domain, Hostname and IP Address
- Component groups
- Keystore configuration
- Address space names
- Ports
- API Mediation Layer configuration
- Cross memory server
- Extensions
#
Zowe prerequisitesJAVA_HOME
: The path where 64-bit Java 8 or later is installed. Only needs to be specified if not already set as a shell variable. Defaults to/usr/lpp/java/J8.0_64
.NODE_HOME
: The path to the Node.js runtime. Only needs to be specified if not already set as a shell variable.ROOT_DIR
: The directory where the Zowe runtime is located, also referred to as the<RUNTIME_DIR>
. Defaults to the location of wherezowe-configure-instance
was executed.ZOSMF_PORT
: The port used by z/OSMF REST services. Defaults to value determined through runningnetstat
.ZOSMF_HOST
: The host name of the z/OSMF REST API services.ZOWE_EXPLORER_HOST
: The hostname of where the Explorer servers are launched from. Defaults to runninghostname -c
. Ensure that this host name is externally accessible from clients who want to use Zowe as well as internally accessible from z/OS itself.ZOWE_IP_ADDRESS
: The IP address of your z/OS system which must be externally accessible to clients who want to use Zowe. This is important to verify for IBM Z Development & Test Environment and cloud systems, where the default that is determined through runningping
anddig
on z/OS returns a different IP address from the external address.
#
Domain, Hostname and IP AddressZOWE_EXPLORER_HOST
: The hostname of where the Explorer servers are launched from. Defaults to runninghostname -c
. Ensure that this host name is externally accessible from clients who want to use Zowe as well as internally accessible from z/OS itself.ZOWE_IP_ADDRESS
: The IP address of your z/OS system which must be externally accessible to clients who want to use Zowe. This is important to verify for IBM Z Development & Test Environment and cloud systems, where the default that is determined through runningping
anddig
on z/OS returns a different IP address from the external address.
When configuring a Zowe instance through the instance.env
file, ZOWE_IP_ADDRESS
and ZOWE_EXPLORER_HOST
are used to specify where the Zowe servers can be reached.
However, these values may not reflect the website name that you access Zowe from. This is especially true in the following cases:
- You are using a proxy
- The URL is a derivative of the value of
ZOWE_EXPLORER_HOST
, such asmyhost
versusmyhost.mycompany.com
In these cases, it may be necessary to specify a value for ZWE_EXTERNAL_HOSTS
in the form of a comma-separated list of the addresses from which you want to access Zowe in your browser.
In the previous example, ZWE_EXTERNAL_HOSTS
could include both myhost
and myhost.mycompany.com
. In the instance.env
, this would look like: ZWE_EXTERNAL_HOSTS=myhost,myhost.mycompany.com
This configuration value maybe used for multiple purposes, including referrer-based security checks. In the case that the values are not specified, referrer checks will use the default values of ZOWE_IP_ADDRESS
, ZOWE_EXPLORER_HOST
, and the system's hostname. Therefore, if these values are not what you put into your browser, you will want to specify ZWE_EXTERNAL_HOSTS
to set the correct value.
ZOWE_EXPLORER_FRAME_ANCESTORS
: The MVS, USS, and JES Explorer are served by their respective explorer UI address spaces. These are accessed through the Zowe desktop where they are hosted as iFrames. To protect against double iFrame security vulnerabilities, browsers all of the valid address that may be used by the browser must be explicitly declared in this property. The default values are:"${ZOWE_EXPLORER_HOST}:*,${ZOWE_IP_ADDRESS}:*"
. If there are any other URLs by which the Zowe Explorers can be served, then these should be appended to the preceding comma-separated list.
#
Component groupsLAUNCH_COMPONENT_GROUPS
: This is a comma-separated list of which z/OS microservice groups are started when Zowe launches.
GATEWAY
will start the API mediation layer that includes the API catalog, the API gateway, and the API discovery service. These three address spaces are Apache Tomcat servers and use the version of Java on z/OS as determined by theJAVA_HOME
value. In addition to the mediation layer, the z/OS Explorer services are included here as well.DESKTOP
will start the Zowe desktop that is the browser GUI for hosting Zowe applications such as the 3270 Terminal emulator or the File Explorer. It will also start ZSS. The Zowe desktop is a node application and uses the version specified by theNODE_HOME
value.ZSS
will start the ZSS server without including the Desktop and Application Framework server. This can be used with Docker so that you do not run servers on z/OS that will already be running within Docker. This may also be useful if you want to utilize ZSS core features or plug-ins without needing the Desktop. ZSS is a pre-requisite for the Zowe desktop, so when theDESKTOP
group is specified then the zss server will be implicitly started. For more information on the zssServer and the technology stack of the Zowe servers see Zowe architecture.- Vendor products may extend Zowe with their own component group that they want to be lifecycled by the Zowe
ZWESVSTC
started task and run as a Zowe sub address space. To do this, specify the fully qualified directory provided by the vendor that contains their Zowe extension scripts. This directory will contain astart.sh
script (required) that is called when theZWESVSTC
started task is launched, aconfigure.sh
script (optional) that performs any configuration steps such as adding iFrame plug-ins to the Zowe desktop, and avalidate.sh
script (optional) that can be used to perform any pre-launch validation such as checking system prerequisites. For more information about how a vendor can extend Zowe with a sub address space, see the Extending section.
Note: If you are using Docker, it is recommended to remove GATEWAY and DESKTOP from LAUNCH_COMPONENT_GROUPS by setting LAUNCH_COMPONENT_GROUPS=ZSS
. This will prevent duplication of servers running both in Docker and on z/OS. Technical Preview
#
Keystore configurationKEYSTORE_DIRECTORY
: This is a path to a zFS directory containing the certificate that Zowe uses to identify itself and encrypt https:// traffic to its clients accessing REST APIs or web pages. This also contains a truststore used to hold the public keys of any z/OS services that Zowe is communicating to, such as z/OSMF. The keystore directory must be created the first time Zowe is installed onto a z/OS system and it can be shared between different Zowe runtimes. For more information about how to create a keystore directory, see Configuring Zowe certificates.
#
Address space namesIndividual address spaces for different Zowe instances and their subcomponents can be distinguished from each other in RMF records or SDSF views by specifying how they are named. Address space names are 8 characters long and made up of a prefix ZOWE_PREFIX
, instance ZOWE_INSTANCE
followed by an identifier for each subcomponent.
ZOWE_PREFIX
: This defines a prefix for Zowe address space STC names. Defaults toZWE
.ZOWE_INSTANCE
: This is appended to theZOWE_PREFIX
to build up the address space name. Defaults to1
A subcomponent will be one of the following values:
- AC - API ML Catalog
- AD - API ML Discovery Service
- AG - API ML Gateway
- DS - App Server
- EF - Explorer API Data Sets
- EJ - Explorer API Jobs
- SZ - ZSS Server
- UD - Explorer UI Data Sets
- UJ - Explorer UI Jobs
- UU - Explorer UI USS
The STC name of the main started task is ZOWE_PREFIX
+ZOWE_INSTANCE
+SV
.
Example:
ZOWE_PREFIX=ZWEZOWE_INSTANCE=X
the first instance of Zowe API ML Gateway identifier will be as follows:
ZWEXAG
Note: If the address space names are not assigned correctly for each subcomponents, check that the step Configure address space job naming has been performed correctly for the z/OS user ID ZWESVUSR
.
#
PortsWhen Zowe starts, a number of its microservices need to be given port numbers that these microservices use to provide access to their services. You can leave default values for components that are not in use. The two most important port numbers are the GATEWAY_PORT
which is for access to the API Gateway through which REST APIs can be viewed and accessed, and ZOWE_ZLUX_SERVER_HTTPS_PORT
which is used to deliver content to client web browsers logging in to the Zowe desktop. All of the other ports are not typically used by clients and used for intra-service communication by Zowe.
CATALOG_PORT
: The port the API Catalog service will use. Used whenLAUNCH_COMPONENT_GROUPS
includesGATEWAY
.DISCOVERY_PORT
: The port the discovery service will use. Used whenLAUNCH_COMPONENT_GROUPS
includesGATEWAY
.GATEWAY_PORT
: The port the API gateway service will use. Used whenLAUNCH_COMPONENT_GROUPS
includesGATEWAY
. This port is used by REST API clients to access z/OS services through the API mediation layer, so should be accessible to these clients. This is also the port used to log on to the API catalog web page through a browser.JOBS_API_PORT
: The port the jobs API service will use. Used whenLAUNCH_COMPONENT_GROUPS
includesGATEWAY
.FILES_API_PORT
: The port the files API service will use. Used whenLAUNCH_COMPONENT_GROUPS
includesGATEWAY
.JES_EXPLORER_UI_PORT
: The port the jes-explorer UI service will use. Used whenLAUNCH_COMPONENT_GROUPS
includesGATEWAY
.MVS_EXPLORER_UI_PORT
: The port the mvs-explorer UI service will use. Used whenLAUNCH_COMPONENT_GROUPS`` includes GATEWAY
.USS_EXPLORER_UI_PORT
: The port the uss-explorer UI service will use. Used whenLAUNCH_COMPONENT_GROUPS
includesGATEWAY
.ZOWE_ZLUX_SERVER_HTTPS_PORT
: The port used by the Zowe desktop. Used whenLAUNCH_COMPONENT_GROUPS
includesDESKTOP
. It should be accessible to client machines with browsers wanting to log on to the Zowe desktop.ZOWE_ZSS_SERVER_PORT
: This port is used by the ZSS server. Used whenLAUNCH_COMPONENT_GROUPS
includesDESKTOP
orZSS
.
Note: If all of the default port values are acceptable, the ports do not need to be changed. To allocate ports for the Zowe runtime servers, ensure that the ports are not in use.
To determine which ports are not available, follow these steps:
Display the list of ports that are in use with the following command:
TSO NETSTAT
Display the list of reserved ports with the following command:
TSO NETSTAT PORTLIST
#
Terminal portsNote: Unlike the ports needed by the Zowe runtime for its Zowe Application Framework and z/OS Services which must be unused, the terminal ports are expected to be in use.
ZOWE_ZLUX_SSH_PORT
: The Zowe desktop contains an application VT Terminal which opens a terminal to z/OS inside the Zowe desktop web page. This port is the number used by the z/OS SSH service and defaults to 22. The USS commandnetstat -b | grep SSHD1
can be used to display the SSH port used on a z/OS system.ZOWE_ZLUX_TELNET_PORT
: The Zowe desktop contains an application 3270 Terminal which opens a 3270 emulator inside the Zowe desktop web page. This port is the number used by the z/OS telnet service and defaults to 23. The USS commandnetstat -b | grep TN3270
can be used to display the telnet port used on a z/OS system.ZOWE_ZLUX_SECURITY_TYPE
: The 3270 Terminal application needs to know whether the telnet service is usingtls
ortelnet
for security. The default value is blank fortelnet
.
#
API Mediation Layer configurationThe following parameters can be set to customize the configuration of all API Mediation Layer components:
APIML_DEBUG_MODE_ENABLED
: When this parameter is set totrue
, detailed logging of activity by the API mediation layer occurs. This can be useful to diagnose unexpected behavior of the API gateway, API discovery, or API catalog services. Default value isfalse
.
The following parameters can be set to customize the configuration of the Discovery:
ZWE_DISCOVERY_SERVICES_LIST
: A comma-separated list of the endpoints for each Discovery Service instance. The default value ishttps://${ZOWE_EXPLORER_HOST}:${DISCOVERY_PORT}/eureka/
.
The following parameters can be set to customize the configuration of the Gateway:
APIML_ALLOW_ENCODED_SLASHES
: When this parameter is set totrue
, the Gateway allows encoded characters to be part of URL requests redirected through the Gateway.APIML_CORS_ENABLED
: When this parameter is set totrue
, CORS are enabled in the API Gateway for Gateway routesapi/v1/gateway/**
.APIML_PREFER_IP_ADDRESS
: Set this parameter totrue
to advertise a service IP address instead of its hostname. Note, this configuration is deprecated. Zowe start script will ignore this value and always set it tofalse
.APIML_GATEWAY_TIMEOUT_MILLIS
: Specifies the timeout for connection to the services in milliseconds.APIML_SECURITY_X509_ENABLED
: Set this parameter totrue
, to enable the client certificate authentication functionality through ZSS.APIML_SECURITY_ZOSMF_APPLID
: The z/OSMF APPLID used for PassTicket.APIML_SECURITY_AUTH_PROVIDER
: The authentication provider used by the API Gateway. By default, the API Gateway uses z/OSMF as an authentication provider. It is possible to switch to SAF as the authentication provider instead of z/OSMF.
The following values are used to customize the configuration of Caching Service.
ZWE_CACHING_SERVICE_PORT=7555
: The port the Caching Service will use.ZWE_CACHING_SERVICE_PERSISTENT=
: This field sets the storage type used to persist data in the Caching Service. Valid options areREDIS
orVSAM
.REDIS
is currently only supported as an off-Z storage solution.VSAM
is only supported on Z.ZWE_CACHING_SERVICE_VSAM_DATASET
: This field sets theVSAM
dataset name to be used to store Caching Service data. This field is required ifZWE_CACHING_SERVICE_PERSISTENT
is set toVSAM
, otherwise this field is not needed.
Refer to detailed section about API Gateway configuration
#
Cross memory serverZOWE_ZSS_XMEM_SERVER_NAME
: For the Zowe Desktop to operate communication with the Zowe cross memory server. The default procedure nameZWESIS_STD
is used for the cross memory server. However, this can be changed in theZWESISTC
PROBLIC member. This might occur to match local naming standards, or to allow isolated testing of a new version of the cross memory server while an older version is running concurrently. The Zowe desktop that runs under theZWESVSTC
started task will locate the appropriate cross memory server running under its started taskZWESISTC
using theZOWE_ZSS_XMEM_SERVER_NAME
value. If this handshake cannot occur, users will be unable to log in to the Zowe desktop. See Troubleshooting: ZSS server unable to communicate with X-MEM.//ZWESISTC PROC NAME='ZWESIS_STD',MEM=00,RGN=0M
ZWES_ZIS_LOADLIB
: The dataset name where the Zowe cross memory server (ZIS) load library resides. Having this value defined can help in automation around ZIS and ZIS plugins.ZWES_ZIS_PLUGINLIB
: The dataset name where plugins for ZIS should be placed. When this is specified, components that contain ZIS plugins will have their load library content placed here.ZWES_ZIS_PARMLIB
: The dataset name where parameters about ZIS should be placed. Having this value defined is necessary for automatically installing ZIS plugins that are within a component.
#
ExtensionsZWEAD_EXTERNAL_STATIC_DEF_DIRECTORIES
: Full USS path to the directory that contains static API Mediation Layer .yml definition files. For more information, see Onboard a REST API without code changes required. Multiple paths should be semicolon separated. This value allows a Zowe instance to be configured so that the API Mediation Layer can be extended by third party REST API and web UI servers.EXTERNAL_COMPONENTS
: For third-party extenders to add the full path to the directory that contains their component lifecycle scripts. For more information, see Zowe lifecycle - Zowe extensions.ZWE_DISCOVERY_SERVICES_LIST
: (Work in progress) Do not modify this value from its supplied default ofhttps://${ZOWE_EXPLORER_HOST}:${DISCOVERY_PORT}/eureka/
.ZWE_CACHING_SERVICE_PORT=7555
: (Work in progress) This port is not yet used so the value does not need to be availale.ZWE_CACHING_SERVICE_PERSISTENT
: (Work in progress) This is used to set the storage type used to persist cached data. Valid options areREDIS
orVSAM
.ZWE_CACHING_SERVICE_VSAM_DATASET
: (Work in progress)
#
Updating the zowe.yaml configuration fileInstead of using instance.env
to configure the Zowe runtime, you can also use a zowe.yaml
file to configure Zowe in more granular level. zowe.yaml
is also required to start Zowe in high availability mode. To make Zowe runtime recognize the zowe.yaml
configuration, you must create a zowe.yaml
file and remove the instance.env
file from the instance directory. See Creating the zowe.yaml file for instructions.
Note: In the following sections, we refer configuration keys with concatenation of key names and dots. For example, if you want to update the configuration key zowe.internalCertificate.keystore.type
with value PKCS12
, you should set value for this entry in the zowe.yaml
:
zowe: internalCertificate: keystore: type: PKCS12
To learn more about the YAML format, please visit yaml.org.
Contents in this section
- Known limitations for Zowe high availability
- Creating the zowe.yaml file
- High level overview of YAML configuration file
- Extract sharable configuration out of zowe.yaml
- Configuration override
- YAML configurations - certificate
- YAML configurations - zowe
- YAML configurations - java
- YAML configurations - node
- YAML configurations - zOSMF
- YAML configurations - components
- Configure component gateway
- Configure component discovery
- Configure component api-catalog
- Configure component caching-service
- Configure component app-server
- Configure component zss
- Configure component jobs-api
- Configure component files-api
- Configure component explorer-jes
- Configure component explorer-mvs
- Configure component explorer-uss
- Configure external extension
- YAML configurations - haInstances
#
Known limitations for Zowe high availability- To allow Sysplex Distributor to route traffic to the Gateway, you can only start one Gateway in each LPAR within the Sysplex. All Gateways instances should be started on the same port configured on Sysplex Distributor.
- Zowe App Server should be accessed through the Gateway with a URL like
https://<dvipa-domain>:<external-port>/zlux/ui/v1
.
#
Creating the zowe.yaml fileThere are two ways to create a zowe.yaml
file.
Copy the example file
<instance-dir>/bin/example-zowe.yaml
to<instance-dir>/zowe.yaml
and modify it based on your configuration.Convert from an existing
instance.env
file by using a utility tool in<instance-dir>/bin/utils/convert-to-zowe-yaml.sh
shipped with Zowe. Issue the following command to convert aninstance.env
file tozowe.yaml
format:<instance-dir>/bin/utils/convert-to-zowe-yaml.sh <instance-dir>/instance.env <instance-dir>/zowe.yaml
where, the
<instance-dir>
is your instance directory path.
After zowe.yaml
is created, you should add new haInstances
section and define ha-instance(s) you want to start in your Sysplex.
#
High level overview of YAML configuration fileThe YAML configuration file has few high level sections:
zowe
: defines global configurations specific to Zowe, including default values.java
: defines Java configurations used by Zowe components.node
: defines node.js configurations used by Zowe components.zOSMF
: tells Zowe your z/OSMF configurations.components
: defines detailed configurations for each Zowe component or extension. Each component or extension may have a key entry under this section. For example,components.gateway
is configuration for API Mediation Layer Gateway service.haInstances
: defines customized configurations for each High Availability (HA) instance. You should predefine all Zowe HA instances you want to start within your Sysplex.
#
Extract sharable configuration out of zowe.yamlThe Zowe YAML configuration file supports a special @include
annotation that can be used in any level of the configuration. This enables you to organize your YAML configuration files and extract sharable configurations to a separate YAML file.
For example, you can define a sharable certificate configuration file <keystore-dir>/zowe-certificates.yaml
like this:
keystore: alias: localhost password: password file: /global/zowe/keystore/localhost/localhost.keystore.p12 type: PKCS12trustStore: file: /global/zowe/keystore/localhost/localhost.truststore.p12 certificateAuthorities: ""pem: key: /global/zowe/keystore/localhost/localhost.keystore.key certificate: /global/zowe/keystore/localhost/localhost.keystore.cer-ebcdic certificateAuthority: /global/zowe/keystore/local_ca/localca.cer-ebcdic
Then in your <instance-dir>/zowe.yaml
, you can import this certification file like this:
zowe: externalCertificate: @include: "<keystore-dir>/zowe-certificates.yaml" internalCertificate: @include: "<keystore-dir>/zowe-certificates.yaml"
#
Configuration overrideInside zowe.yaml
, you can define default values and they may be overridden in more granular level configurations. This can happen in several ways:
Component can override default certificate configuration. For specific entry of certification configuration, if it's not overridden, it will fall back to default configurations. For example, in this configuration:
zowe: internalCertificate: keystore: alias: localhost password: password file: /global/zowe/keystore/localhost/localhost.keystore.p12 type: PKCS12 trustStore: file: /global/zowe/keystore/localhost/localhost.truststore.p12 certificateAuthorities: "" pem: key: /global/zowe/keystore/localhost/localhost.keystore.key certificate: /global/zowe/keystore/localhost/localhost.keystore.cer-ebcdic certificateAuthority: /global/zowe/keystore/local_ca/localca.cer-ebcdiccomponents: app-server: certificate: keystore: alias: app-server pem: key: /global/zowe/keystore/localhost/localhost.keystore.app-server.key certificate: /global/zowe/keystore/localhost/localhost.keystore.app-server.cer-ebcdic
App Server will use the certificate alias
app-server
instead oflocalhost
from the same keystore defined inzowe.internalCertificate.keystore.file
. And it will use the exact same truststore defined inzowe.internalCertificate.trustStore.file
.HA instance component configuration
haInstances.<ha-instance>.components.<component>
can override global level component configurationscomponents.<component>
. Any configuration you can find incomponents.<component>
level can be overridden inhaInstances.<ha-instance>.components.<component>
level. For example, in this configuration:components: app-server: enabled: true port: 8544haInstances: lpar2a: components: app-server: enabled: false lpar2b: components: app-server: port: 28544
App Server on
lpar2a
HA instance will not be started. Onlpar2b
HA instance, it will be started but on port 28544.
#
YAML configurations - certificateIn Zowe YAML configuration, certificate definition shares the same format and this format can be used in several configuration entries. For example, zowe.externalCertificate
, zowe.internalCertificate
, components.<component>.certificate
, and haInstances.<ha-instance>.components.<component>.certificate
. The certificate definition may include the following entries:
keystore.type
: Defines the type of the keystore. If you are using keystore, this value usually should bePKCS12
. If you are using keyring, this value should beJCERACFKS
.keystore.file
: Defines the path of the keystore file. If you are using keyring, this should look likesafkeyring:////<keyring-owner>/<keyring-name>
. For example,safkeyring:////ZWESVUSR/ZoweKeyring
.keystore.alias
: represents the alias name of the certificate stored in keystore. If you are using keyring, this is the certificate label connected to the keyring.keystore.password
: Defines the password of the keystore.trustStore.file
: Defines the path to the truststore file. If you are using keyring, this should look likesafkeyring:////<keyring-owner>/<keyring-name>
, usually will be the same value ofkeystore.file
.trustStore.certificateAuthorities
: defines extra certificate authorities you will trust. This should point to CA files in PEM format.pem.key
: Defines the private key file in PEM format. This can be used by applications that do not support either PKCS12 keystore format or z/OS keyring.pem.certificate
: Defines the public key file in PEM format. This can be used by applications that do not support either PKCS12 keystore format or z/OS keyring.pem.certificateAuthority
: Defines certificate authorities in PEM format. This can be used by applications that do not support either PKCS12 keystore format or z/OS keyring.
Note: With the zowe.yaml
configuration, all certificate related configurations are merged into the zowe.yaml
file. <keystore-dir>/zowe-certificates.env
will not be used.
#
YAML configurations - zoweThe high-level configuration zowe
supports these definitions:
zowe.runtimeDirectory
: Tells Zowe the runtime directory connected to this Zowe instance. This is equivalent to theROOT_DIR
variable in theinstance.env
file.zowe.extensionDirectory
: Tells Zowe where you put the runtime of all your extensions. This is equivalent to theZWE_EXTENSION_DIR
variable in theinstance.env
file.zowe.jobPrefix
: Defines the Zowe job prefix for the ZWESVSTC started task. This is equivalent to theZOWE_PREFIX
variable in theinstance.env
file.zowe.identifier
: Defines the Zowe job identifier for the ZWESVSTC started task. This is equivalent to theZOWE_INSTANCE
variable in theinstance.env
file.zowe.externalDomains
: Defines a list of external domains that will be used by the Zowe instance. This configuration is an array of domain name strings. This is equivalent to theZWE_EXTERNAL_HOSTS
variable in theinstance.env
file but should be represented as an array. In Sysplex deployment, this is the DVIPA domain name defined in Sysplex Distributor. For example,zowe: externalDomains: - external.my-company.com - additional-dvipa-domain.my-company.com
zowe.externalPort
: Defines the port that will be exposed to external Zowe users. By default, this value is set based on theGATEWAY_PORT
variable in the in theinstance.env
file. In Sysplex deployment, this is the DVIPA port defined in Sysplex Distributor. See Configure Sysplex Distributor for more information.zowe.environments
: Defines extra environment variables to customize the Zowe runtime. This configuration is a list of key / value pairs. This is equivalent to adding new environment variables to theinstance.env
file. For example,zowe: environments: MY_NEW_ENV: value-of-my-env
zowe.externalCertificate
: Defines the northbound certificate facing Zowe users. These configurations are defined in<keystore-dir>/zowe-certificates.env
.Note: This configuration is not the same as the
EXTERNAL_CERTIFICATE
configuration inzowe-setup-certificates.env
. Inzowe-setup-certificates.env
,EXTERNAL_CERTIFICATE
means that the certificate is not generated by thezowe-setup-certificates.sh
utility script.zowe.internalCertificate
: Defines the default southbound certificate used within Zowe services. These configurations are defined in<keystore-dir>/zowe-certificates.env
. By default, this is the same aszowe.externalCertificate
.zowe.sso.token.name
: Defines SSO token name. This is equivalent to thePKCS11_TOKEN_NAME
variable in<keystore-dir>/zowe-certificates.env
.zowe.sso.token.label
: Defines the certificate label that binds to SSO token. This is equivalent to thePKCS11_TOKEN_LABEL
variable in<keystore-dir>/zowe-certificates.env
.zowe.launcher
: The launcher section defines defaults about how the Zowe launcher should act upon components.zowe.launcher.restartIntervals
: An array of positive integers that defines how many times a component should be tried to be restarted if it fails, and how much time to wait in seconds for that restart to succeed before retrying.zowe.launcher.minUptime
: The minimum amount of time a zowe component should be running in order to be declared as started successfully.zowe.launcher.shareAs
: Whether or not the launcher should start components in the same address space as it. See documentation for _BPX_SHAREAS for details.
#
YAML configurations - javaThe high-level configuration java
supports these definitions:
home
: Defines the path to the Java runtime directory. This is equivalent to theJAVA_HOME
variable in theinstance.env
file.
#
YAML configurations - nodeThe high-level configuration node
supports these definitions:
home
: Defines the path to the Node.js runtime directory. This is equivalent to theNODE_HOME
variable in theinstance.env
file.
#
YAML configurations - zOSMFThe high-level configuration zOSMF
supports these definitions:
zOSMF.host
: Defines the hostname of your z/OSMF instance. This is equivalent to theZOSMF_HOST
variable in theinstance.env
file.zOSMF.port
: Defines the port of your z/OSMF instance. This is equivalent to theZOSMF_PORT
variable in theinstance.env
file.zOSMF.applId
: Defines the application ID of your z/OSMF instance. This is equivalent to theAPIML_SECURITY_ZOSMF_APPLID
variable in theinstance.env
file.
#
YAML configurations - componentsAll Zowe components and extensions can have a dedicated section under the components
high-level configuration.
In this section, <component>
represents any Zowe components or extensions. For all components and extensions, these are the common definitions.
components.<component>.enabled
: Defines if you want to start this component in this Zowe instance. This is a much detailed granular definition of theLAUNCH_COMPONENT_GROUPS
variable ininstance.env
. This allows you to control each component instead of a group. For external components, also known as extensions, this configuration also replaces theEXTERNAL_COMPONENTS
variable ininstance.env
.components.<component>.certificate
: you can customize a component to use different certificate from default values. This section follows same format defined in YAML configurations - certificate. If this is not customized, the component will use certificates defined inzowe.internalCertificate
.components.<component>.launcher
: Any component can have a launcher section which overrides the overall Zowe Launcher default defined inzowe.launcher
.
#
Configure component gatewayThese configurations can be used under the components.gateway
section:
port
: Defines the port which the gateway should be started on. This is equivalent to theGATEWAY_PORT
variable ininstance.env
.debug
: Defines whether to enable debug mode for gateway. This is equivalent to theAPIML_DEBUG_MODE_ENABLED
variable ininstance.env
but with better granular level.apiml.service.allowEncodedSlashes
: When this parameter is set totrue
, the Gateway allows encoded characters to be part of URL requests redirected through the Gateway. This is equivalent to theAPIML_ALLOW_ENCODED_SLASHES
variable ininstance.env
.apiml.service.corsEnabled
: When this parameter is set totrue
, CORS are enabled in the API Gateway for Gateway routesapi/v1/gateway/**
. This is equivalent to theAPIML_CORS_ENABLED
variable ininstance.env
.apiml.service.preferIpAddress
: Set this parameter totrue
to advertise a service IP address instead of its hostname. Note: This configuration is deprecated. Zowe start script will ignore this value and always set it tofalse
. This is equivalent to theAPIML_PREFER_IP_ADDRESS
variable ininstance.env
.apiml.gateway.timeoutMillis
: Specifies the timeout for connection to the services in milliseconds. This is equivalent to theAPIML_GATEWAY_TIMEOUT_MILLIS
variable ininstance.env
.apiml.security.x509.enabled
: Set this parameter totrue
to enable the client certificate authentication functionality through ZSS. This is equivalent to theAPIML_SECURITY_X509_ENABLED
variable ininstance.env
.apiml.security.x509.externalMapperUrl
: Defines the URL where Gateway can query the mapping of client certificates. This is equivalent to theAPIML_GATEWAY_EXTERNAL_MAPPER
variable ininstance.env
.apiml.security.zosmf.applid
: Defines the z/OSMF APPLID used for PassTicket. This is equivalent to theAPIML_SECURITY_ZOSMF_APPLID
variable ininstance.env
. This should have the same value ofzOSMF.applId
. This entry is kept for backward compatibility.apiml.security.auth.provider
: Defines the authentication provider used by the API Gateway. This is equivalent to theAPIML_SECURITY_AUTH_PROVIDER
variable ininstance.env
.apiml.security.authorization.endpoint.url
: Defines the URL to the authorization endpoint. This endpoint tells Gateway if a user has a particular permission on SAF profile. For example, permission to theAPIML.SERVICES
profile ofZOWE
class. This is equivalent to theAPIML_SECURITY_AUTHORIZATION_ENDPOINT_URL
variable ininstance.env
.apiml.security.ssl.verifySslCertificatesOfServices
: Defines whether APIML should verify certificates of services in strict mode. Setting totrue
will enable thestrict
mode where APIML will validate if the certificate is trusted in turststore, and also if the certificate Common Name or Subject Alternate Name (SAN) matches the service hostname. This is equivalent to theVERIFY_CERTIFICATES
variable defined in<keystore-dir>/zowe-certificates.env
.apiml.security.ssl.nonStrictVerifySslCertificatesOfServices
: Defines whether APIML should verify certificates of services in non-strict mode. Setting the value totrue
will enable thenon-strict
mode where APIML will validate if the certificate is trusted in turststore, but ignore the certificate Common Name or Subject Alternate Name (SAN) check. Zowe will ignore this configuration when strict mode is enabled withapiml.security.ssl.verifySslCertificatesOfServices
. This is equivalent to theNONSTRICT_VERIFY_CERTIFICATES
variable defined in<keystore-dir>/zowe-certificates.env
.apiml.server.maxConnectionsPerRoute
: Specifies the maximum connections for each service. This is equivalent to theAPIML_MAX_CONNECTIONS_PER_ROUTE
variable ininstance.env
.apiml.server.maxTotalConnections
: Specifies the total connections for all services registered under API Mediation Layer. This is equivalent to theAPIML_MAX_TOTAL_CONNECTIONS
variable ininstance.env
.
#
Configure component discoveryThese configurations can be used under the components.discovery
section:
port
: Defines the port which discovery should be started on. This is equivalent to theDISCOVERY_PORT
variable ininstance.env
.debug
: Defines whether to enable debug mode for gateway. This is equivalent to theAPIML_DEBUG_MODE_ENABLED
variable ininstance.env
but with better granular level.apiml.service.preferIpAddress
: Set this parameter totrue
to advertise a service IP address instead of its hostname. Note: This configuration is deprecated. The Zowe start script will ignore this value and always set it tofalse
. This is equivalent to theAPIML_PREFER_IP_ADDRESS
variable ininstance.env
.apiml.security.ssl.verifySslCertificatesOfServices
: Defines whether APIML should verify certificates of services in strict mode. Setting totrue
will enable thestrict
mode where APIML will validate both if the certificate is trusted in turststore, and also if the certificate Common Name or Subject Alternate Name (SAN) matches the service hostname. This is equivalent to theVERIFY_CERTIFICATES
variable defined in<keystore-dir>/zowe-certificates.env
.apiml.security.ssl.nonStrictVerifySslCertificatesOfServices
: Defines whether APIML should verify certificates of services in non-strict mode. Setting totrue
will enable thenon-strict
mode where APIML will validate if the certificate is trusted in turststore, but ignore the certificate Common Name or Subject Alternate Name (SAN) check. Zowe will ignore this configuration if strict mode is enabled withapiml.security.ssl.verifySslCertificatesOfServices
. This is equivalent to theNONSTRICT_VERIFY_CERTIFICATES
variable defined in<keystore-dir>/zowe-certificates.env
.alternativeStaticApiDefinitionsDirectories
: Specifies the alternative directories of static definitions. This is equivalent to theAPIML_MAX_CONNECTIONS_PER_ROUTE
variable ininstance.env
.apiml.server.maxTotalConnections
: Specifies the total connections for all services registered under API Mediation Layer. This is equivalent to theZWEAD_EXTERNAL_STATIC_DEF_DIRECTORIES
variable ininstance.env
.
#
Configure component api-catalogThese configurations can be used under the components.api-catalog
section:
port
: Defines the port which API Catalog should be started on. This is equivalent to theCATALOG_PORT
variable ininstance.env
.debug
: Defines if we want to enable debug mode for gateway. This is equivalent to theAPIML_DEBUG_MODE_ENABLED
variable but with better granular level.environment.preferIpAddress
: Set this parameter totrue
to advertise a service IP address instead of its hostname. Note: This configuration is deprecated. Zowe start script will ignore this value and always set it tofalse
. This is equivalent to theAPIML_PREFER_IP_ADDRESS
variable ininstance.env
.
#
Configure component caching-serviceThese configurations can be used under the components.caching-service
section:
port
: Defines the port which Caching Service should be started on. This is equivalent to theZWE_CACHING_SERVICE_PORT
variable ininstance.env
.debug
: Defines if we want to enable debug mode for gateway. This is equivalent to theAPIML_DEBUG_MODE_ENABLED
variable ininstance.env
but with better granular level.storage.mode
: Sets the storage type used to persist data in the Caching Service. This is equivalent to theZWE_CACHING_SERVICE_PERSISTENT
variable ininstance.env
.storage.size
: Specifies amount of records before eviction strategies start evicting. This is equivalent to theZWE_CACHING_STORAGE_SIZE
variable ininstance.env
.storage.evictionStrategy
: Specifies eviction strategy to be used when the storage size is achieved. This is equivalent to theZWE_CACHING_EVICTION_STRATEGY
variable ininstance.env
.storage.vsam.name
: Specifies the data set name of the caching service VSAM data set. This is equivalent to theZWE_CACHING_SERVICE_VSAM_DATASET
variable ininstance.env
.storage.redis.masterNodeUri
: Specifies the URI used to connect to the Redis master instance in the formusername:password@host:port
. This is equivalent to theCACHING_STORAGE_REDIS_MASTERNODEURI
variable ininstance.env
.storage.redis.timeout
: Specifies the timeout second to Redis. Defaults to 60 seconds. This is equivalent to theCACHING_STORAGE_REDIS_TIMEOUT
variable ininstance.env
.storage.redis.sentinel.masterInstance
: Specifies the Redis master instance ID used by the Redis Sentinel instances. This is equivalent to theCACHING_STORAGE_REDIS_SENTINEL_MASTERINSTANCE
variable ininstance.env
.storage.redis.sentinel.nodes
: Specifies the array of URIs used to connect to a Redis Sentinel instances in the formusername:password@host:port
. This is equivalent to theCACHING_STORAGE_REDIS_SENTINEL_NODES
variable ininstance.env
.storage.redis.ssl.enabled
: Specifies the boolean flag indicating if Redis is being used with SSL/TLS support. Defaults totrue
. This is equivalent to theCACHING_STORAGE_REDIS_SSL_ENABLED
variable ininstance.env
.storage.redis.ssl.keystore
: Specifies the keystore file used to store the private key. This is equivalent to theCACHING_STORAGE_REDIS_SSL_KEYSTORE
variable ininstance.env
.storage.redis.ssl.keystorePassword
: Specifies the password used to unlock the keystore. This is equivalent to theCACHING_STORAGE_REDIS_SSL_KEYSTOREPASSWORD
variable ininstance.env
.storage.redis.ssl.truststore
: Specifies the truststore file used to keep other parties public keys and certificates. This is equivalent to theCACHING_STORAGE_REDIS_SSL_TRUSTSTORE
variable ininstance.env
.storage.redis.ssl.truststorePassword
: Specifies the password used to unlock the truststore. This is equivalent to theCACHING_STORAGE_REDIS_SSL_TRUSTSTOREPASSWORD
variable ininstance.env
.environment.preferIpAddress
: Set this parameter totrue
to advertise a service IP address instead of its hostname. Note: this configuration is deprecated. Zowe start script will ignore this value and always set it tofalse
. This is equivalent to theAPIML_PREFER_IP_ADDRESS
variable ininstance.env
.apiml.security.ssl.verifySslCertificatesOfServices
: Specifies whether APIML should verify certificates of services in strict mode. Set totrue
will enablestrict
mode that APIML will validate both if the certificate is trusted in turststore, and also if the certificate Common Name or Subject Alternate Name (SAN) match the service hostname. This is equivalent to theVERIFY_CERTIFICATES
variable defined in<keystore-dir>/zowe-certificates.env
.apiml.security.ssl.nonStrictVerifySslCertificatesOfServices
: Defines whether APIML should verify certificates of services in non-strict mode. Setting totrue
will enablenon-strict
mode where APIML will validate if the certificate is trusted in turststore, but ignore the certificate Common Name or Subject Alternate Name (SAN) check. Zowe will ignore this configuration if strict mode is enabled withapiml.security.ssl.verifySslCertificatesOfServices
. This is equivalent to theNONSTRICT_VERIFY_CERTIFICATES
variable defined in<keystore-dir>/zowe-certificates.env
.
#
Configure component app-serverThese configurations can be used under the components.app-server
section:
port
: Defines the port which App Server should be started on. This is equivalent to theZOWE_ZLUX_SERVER_HTTPS_PORT
variable ininstance.env
.
#
Configure component zssThese configurations can be used under the components.zss
section:
port
: Defines the port which ZSS should be started on. This is equivalent to theZOWE_ZSS_SERVER_PORT
variable ininstance.env
.crossMemoryServerName
: Defines the procedure name of cross memory server. This is equivalent to theZOWE_ZSS_XMEM_SERVER_NAME
variable ininstance.env
.tls
: Defines whether ZSS service has enabled TLS. This is equivalent to theZOWE_ZSS_SERVER_TLS
variable ininstance.env
.
#
Configure component jobs-apiThese configurations can be used under the components.jobs-api
section:
port
: Defines the port which Jobs API should be started on. This is equivalent to theJOBS_API_PORT
variable ininstance.env
.
#
Configure component files-apiThese configurations can be used under the components.files-api
section:
port
: Defines the port which Files API should be started on. This is equivalent to theFILES_API_PORT
variable ininstance.env
.
#
Configure component explorer-jesThese configurations can be used under the components.explorer-jes
section:
port
: Defines the port which JES UI Explorer should be started on. This is equivalent to theJES_EXPLORER_UI_PORT
variable ininstance.env
.frameAncestors
: Defines the frame ancestors supported by UI Explorer. This is equivalent to theZOWE_EXPLORER_FRAME_ANCESTORS
variable ininstance.env
but in better granular level.
#
Configure component explorer-mvsThese configurations can be used under the components.explorer-mvs
section:
port
: Defines the port which MVS UI Explorer should be started on. This is equivalent to theMVS_EXPLORER_UI_PORT
variable ininstance.env
.frameAncestors
: Defines the frame ancestors supported by UI Explorer. This is equivalent to theZOWE_EXPLORER_FRAME_ANCESTORS
variable ininstance.env
but in better granular level.
#
Configure component explorer-ussThese configurations can be used under the components.explorer-uss
section:
port
: Defines the port which USS UI Explorer should be started on. This is equivalent to theUSS_EXPLORER_UI_PORT
variable ininstance.env
.frameAncestors
: Defines the frame ancestors supported by UI Explorer. This is equivalent to theZOWE_EXPLORER_FRAME_ANCESTORS
variable ininstance.env
but in better granular level.
#
Configure external extensionYou can define a components.<extension-id>
section and use common component configuration entries.
For example, enable my-extension
:
components: # for extensions, you can add your definition like this my-extension: enabled: true
#
YAML configurations - haInstancesAll Zowe high availability instances should have a dedicated section under the haInstances
high-level configuration.
In this section, <ha-instance>
represents any Zowe high availability instance ID.
For all high availability instances, these are the common definitions.
haInstances.<ha-instance>.hostname
: Defines the host name where you want to start this instance. This could be the host name of one LPAR in your Sysplex.haInstances.<ha-instance>.ip
: Defines the IP address where you want to start this instance. This could be the IP address of one LPAR in your Sysplex.haInstances.<ha-instance>.components.<component>
: Optional settings you can override component configurations for this high availability instance. See Configuration override for more details.
#
Hints and tipsLearn about some hints and tips that you might find useful when you create and configure the Zowe instance.
When you are configuring Zowe on z/OS, you need to create certificates, and then create the Zowe instance.
The creation of a Zowe instance is controlled by the instance.env
file in your instance directory INSTANCE_DIR
.
Keystore
Edit the
instance.env
file to set the keystore directory to the one you created when you ranzowe-setup-certificates.sh
.The keyword and value in
instance.env
should be the same as inzowe-setup-certificates.env
, as shown belowKEYSTORE_DIRECTORY=/my/zowe/instance/keystore
Hostname and IP address
The
zowe-configure-instance.sh
script handles the IP address and hostname the same wayzowe-setup-certificates.sh
does.In
instance.env
, you specify the IP address and hostname using the following keywords:ZOWE_EXPLORER_HOST=ZOWE_IP_ADDRESS=
The
ZOWE_EXPLORER_HOST
value must resolve to the external IP address, otherwise you should use the external IP address as the value forZOWE_EXPLORER_HOST
.The
zowe-configure-instance.sh
script will attempt to discover the IP address and hostname of your system if you leave these unset.When the script cannot determine the hostname or the IP address, it will ask you to enter the IP address manually during the dialog. If you have not specified a value for
ZOWE_EXPLORER_HOST
, then the script will use the IP address as the hostname.The values of
ZOWE_EXPLORER_HOST
andZOWE_IP_ADDRESS
that the script discovered are appended to theinstance.env
file unless they were already set in that file or as shell environment variables before you ran the script.