Enterprise rollout of Zowe CLI
{Core} As consumer use of The Open Mainframe Project’s Zowe CLI matures, consumer sites have begun to look for ways to deploy Zowe CLI for all of their users in a production environment. In this article, I discuss effective ways to create a Zowe CLI configuration, describe techniques for sharing a configuration with your entire organization, and identify how you can deploy Zowe CLI in a restricted environment.
Specifically, we will explore:
- Advantages of Zowe CLI V2 team configuration over V1 profiles
- Creating a V2 team configuration
- Sharing a Zowe CLI team configuration
- Locating your team configuration values
- Sharing plugins with your entire team
- Installing Zowe CLI into a custom location
Advantages of Zowe CLI V2 team configuration over V1 profiles
The Zowe V1 configuration consisted of many files in a known directory structure. While multiple profiles of a particular type could be created, that single V1 directory structure represented your only available configuration.
The use of this directory structure created some inherent limitations.
- Each user had to understand, specify, and maintain their own profiles. Often the details needed to successfully connect to the desired services were not known to many in the user community. Having to uncover so much unknown information became a roadblock to adoption.
- Profiles could not inherit properties from other profiles. This lead to repeated entry of the same property values.
- You only had one configuration per laptop. As you switched your efforts from one project to another, you had to re-configure this one available configuration to suit your next project.
- Because multiple files and directories were involved in the configuration, it was difficult to share this configuration with co-workers.
With the Zowe CLI V2 team configuration, all profiles and properties can be maintained in single JSON file named zowe.config.json.
Once one person creates a working set of configuration properties, it is much easier to share this one file with an entire department. By sharing this configuration with an entire team, only that one person has to create and test the configuration. Every other person on the team will not have to replicate that same effort.
The configuration created by the “zowe config init” command is a simplified one-level structure (similar to the one-level structure of V1). However, by editing this file you can nest profiles under other profiles. For example, you could nest several different types of profiles under one host name. You would not have to duplicate the host name or the credentials for the various profiles if those properties did not differ.
You can place your configuration file at a global location (within the $ZOWE_CLI_HOME directory). That configuration file will be used for Zowe commands regardless of the directory in which you are located when you run your Zowe commands. Placing your configuration file into $ZOWE_CLI_HOME is much like the only configuration choice available in V1.
With a Zowe V2 team configuration, you have the added flexibility of placing a configuration file into an arbitrary directory on your laptop. Perhaps you work on several different projects, whose associated files are located in separate directories. You can place a different Zowe CLI configuration file into each of those directories. By changing into the directory for your desired project, you will automatically change your effective Zowe CLI configuration to something appropriate for that project.
You can create both a global configuration and project configuration files. Depending on your current directory, both can be in effect at the same time.
The V2 team configuration also supports a “user configuration” file (zowe.config.user.json). The user configuration enables you to specify property values that only apply to you and should not be shared with other team members. This makes it even easier to safely share the team configuration file (zowe.config.json) with everyone on your team.
Both Zowe CLI and Zowe Explorer will recognize and update a V2 team configuration.
Team configuration details
The following two documents provide details on how a global configuration, project configuration, and user configurations are combined to provide the options in-effect when you run a Zowe command.
A description of how Zowe commands combine properties from multiple configuration files is available on our Zowe documentation site under the topic named: “How Zowe CLI uses configurations”.
An engineering whitepaper contains best practices for your use of configuration files and describes many specific scenarios: “How Zowe CLI team configuration files are merged together” .
V1 configuration is deprecated in Zowe CLI V2
V1 configurations and their associated “zowe profiles” commands are fully functional in Zowe CLI V2. They remain operational to enable consumers to migrate on their own timeline from a V1 configuration to a V2 team configuration.
However, the V1 “zowe profiles” commands have been deprecated. The CLI on-line help reflects that deprecation. Even though the “zowe profiles” commands work successfully, each such command also displays a warning that the command has been deprecated.
The Zowe CLI team plans to remove all functionality for V1 profiles from the Zowe CLI V3 release.
Creating a V2 team configuration
Several options exist to help you create a team configuration. Depending on your current environment, one may be better suited to your needs.
Convert a V1 configuration to a V2 team configuration
The simplest way for existing Zowe CLI V1 consumers to get started with a V2 team configuration, is to let Zowe automatically convert your V1 configuration to a V2 team configuration. You can trigger that conversion with the following command: zowe config convert-profiles
Your old configuration is replicated in a V2 team configuration. This means that:
- All of your old profiles with all of their old values are recreated in the team configuration.
- All profiles are created into a team configuration within a one-level structure. The conversion replicates that limited one-level structure available from your V1 configuration. You can edit your V2 team configuration file to create a more complex structure if that suits the needs of your site.
- If you used plain-text credentials in your V1 configuration, your resulting V2 team configuration will also contain plain-text credentials. The conversion program faithfully replicates what you had previously. To share such a V2 team configuration with other team members, you should first change those credentials into securely stored properties. The Zowe documentation topic “Team configuration for team leaders” contains examples of making “user” and “password” secure properties. Once properties are marked as secure, they are stored only for you on your own laptop.
Create a starter team configuration
If you are starting from scratch in V2 (i.e., you have no existing V1 configuration) Zowe CLI has commands to help you get started.
The command 'zowe config init'will create a template for a new team configuration. It will not have values for all properties. You will have to add values for situations like: you have multiple hosts, you need site-specific port numbers, or you use a service that has service-specific properties and values. None-the-less, the template that is created provides the correct structure for you to easily edit the configuration and add your required properties and values.
Taking advantage of base profiles
Base profiles existed in our V1 release, and they still provide value in a V2 team configuration. The recommended use of a base profile is to store the host, port, user, and password to connect to the Zowe API Mediation Layer (APIML) server, which will dispatch REST requests to all of your other services. In an APIML scenario, no other service profile needs a host, port, user, or password property. If your site uses APIML security tokens, your token is stored in your base profile instead of user and password.
The more general behavior of a base profile is that you can supply key connection properties whose values will be used when those properties are NOT supplied in a specific service profile (like a zosmf profile).
One scenario in which you might benefit from using a base profile is when you have multiple services (zosmf, CICS, DB2, etc) all on the same host and you are NOT currently running APIML to automatically dispatch requests to the appropriate service. By placing the “host” property in a base profile, you do not have to specify that same host property in each individual service profile (zosmf, CICS, DB2, etc).
A base profile can also be useful (again in a non-APIML deployment) when you use the same credentials on all of your hosts and all of your services. By placing the “user” and “password” properties in a base profile, they will be used for every service profile that has no credentials specified. While this approach does not create a true single sign-on environment, it does save having to replicate the same credentials in every service profile for which you use the same credentials.
By default, Zowe CLI will only accept certificates that have been properly signed by a trusted third party Certificate Authority. When your site uses self-signed certificates for your REST services, you must tell Zowe CLI to accept self-signed certificates. Since the decision to use self-signed certificates is typically a site-wide decision, setting the “rejectUnauthorized” property to false in a base profile causes Zowe CLI to automatically accept self-signed certificates for all existing (and future) service profiles.
You are not locked into your base profile choices. If one service runs on a different host or uses different credentials, you simply specify those properties in that service’s profile. A property value in a service profile will always be used instead of the property specified in a base profile. In this fashion, it is easy to create an exception to the rule.
The “zowe config init” command creates a simple configuration structure to help people get started with their Zowe CLI configuration. In that spirit, it creates a configuration in which all services run on one host and all use the same credentials (which are securely stored). It also sets the “rejectUnauthorized” property to reject self-signed certificates (we always make the most secure choice by default). As always, you can hand-modify this zowe.config.json file to reflect the needs of your site. However, the base profile generated by “zowe config init” to support this simple configuration is a good example of how a base profile can affect every other profile in your configuration.
{
"$schema": "./zowe.schema.json",
"profiles": {
... profiles with no host, user, password or rejectUnauthorized ...
"base": {
"type": "base",
"properties": {
"host": "Your.Mainframe.HostName.com",
"rejectUnauthorized": true
},
"secure": [
"user",
"password"
]
}
}
... stuff ommitted ...
}Use APIML to create a working team configuration
If your site uses the Zowe API Mediation Layer (APIML), you can use the command 'zowe config auto-init'. That command will combine information from your installed plugins with information from APIML to create a Zowe CLI configuration that has valid connection properties automatically populated for your site.
Sharing a Zowe CLI team configuration
After a trailblazer (who is most likely to be a tools administrator within your organization) configures Zowe CLI to fit the exact needs of your project, you want everyone on the project team to use the same configuration. However, those teammates can get started much faster if each person does not have to repeat the configuration process.
Two files are created by Zowe tools like the “zowe config init” command: zowe.config.json and zowe.schema.json. Users typically only inspect and use the zowe.config.json file. The zowe.schema.json file was designed to be used by an editor (like Visual Studio Code) to provide IntelliSense-like assistance.
Personally deliver the files
Starting with the most low-tech approach, you can figuratively “hand the files to another person” by placing these two files on a USB drive or attaching the files to an email. The recipient would place the two files into either their global directory or into a project-specific directory.
While this approach requires no setup effort, when some aspect of your configuration must be changed, you must initiate the transfer of a modified configuration to each person again.
Stage the files on a network server
If you place the configuration files on a Windows share, a Linux NFS server, or an HTTP web server, you can update the files when needed, and recipients can obtain the latest configuration at any time. This might be the best approach if everyone on your team each uses a single global configuration.
Zowe CLI provides the following command to simplify the recipient’s effort to copy the files to their proper place. The command copies both the zowe.config.json file and the zowe.schema.json file that it references to your current directory.
zowe config import Path_To_Your_Network_Directory/zowe.config.jsonIf you supply the "--global-config"option to that command, it will place those files into your global configuration location. If you want to update your existing configuration, you add the"--overwrite"option.
If you use an HTTP web server, you can specify a URL to your zowe.config.json file. However, if the web server uses redirection to access the files on that server, the “zowe config import” command will be unable to retrieve the associated zowe.schema.json file. The “config import” command uses the URL of the specified config file to form a comparable path to the associated schema file. The two URL paths are not interchangeable on a web server that uses redirection. The Box cloud storage application is an example of a server that uses redirection.
When your web server redirects your URLs, you can simply download both files to your local machine. You can hand-place those files into the desired location, or you can use the “config import” command to copy the downloaded files into your desired location.
Maintain configuration files under source control
As mentioned earlier, you have the option of placing different configuration files into different directories on your workstation that represent the different projects on which your team works. If you keep your project-related files under a source control system like GitHub, you will provide the best experience for your team by also keeping your project-specific Zowe configuration files under source control.
As with the other techniques, a trailblazer establishes the desired configuration. That person commits the configuration to source control. All team members will automatically get the configuration when they get the project source files from source control. This is especially helpful when new people join the team. They will not have to take a separate step to get the Zowe CLI configuration. They simply get it with the rest of their project files.
Updates are equally simple. The trailblazer makes an update and commits the changes. The recipients simply refresh their source files.
Recipient actions after receiving a configuration
The model used by every technique above has a common characteristic: a trailblazer creates a configuration and every other teammate benefits from that work. Those other teammates still have to do some further configuration, right? The answer is very little.
Assume that the trailblazer configures as follows:
- Specifies all of the site-specific shared information.
- Uses the Zowe CLI secure credential manager. That is the default generated by the “zowe config init” command.
- Specifies that missing connection properties should be auto-stored. The “zowe config init” command automatically sets the autoStore property in the zowe.config.json file that it generates. If you hand-craft your own configuration file, you add the property named “autoStore” as a top-level property in your configuration file. The following snippet contains an example of enabling the autoStore property.
{
"$schema": "./zowe.schema.json",
"profiles": {
... stuff ommitted ...
},
"defaults": {
... stuff ommitted ...
},
"autoStore": true
}The only thing that will be missing for other teammates will be their credentials. The zowe.config.json file has a record that user and password are needed properties, and that those properties must be stored in the secure credential store.
The slick part of this process results from a characteristic of Zowe CLI commands in which they prompt for any required connection properties that are missing. As a result, after a teammate receives a Zowe config file, that person just starts typing desired Zowe commands. They will be prompted for their user and password on the first command. Because the autoStore property is set to true, those values are automatically stored in the secure credential store. Future commands no longer need to ask for the user and password.
The following snippet shows an example of an action that a recipient might take which will automatically finalize their configuration. The second repeated command shows how you are not prompted after your first command.
-> zowe zos-files list data-set "SYS1.PARMLIB*"
Enter the user name for your service (will be hidden):
Enter the password for your service (will be hidden):
Stored properties in C:\Users\YourUserId\.zowe\zowe.config.json: user, password
SYS1.PARMLIB
SYS1.PARMLIB.ARCHIVE
SYS1.PARMLIB.OLD
SYS1.PARMLIBN
-> zowe zos-files list data-set "SYS1.PARMLIB*"
SYS1.PARMLIB
SYS1.PARMLIB.ARCHIVE
SYS1.PARMLIB.OLD
SYS1.PARMLIBNRecipients who use Zowe Explorer have a similar experience when they receive a team configuration. Of course, they are prompted for their credentials with graphical popup questions, adhering to the standard behavior of a Visual Studio Code extension. As with Zowe CLI, if the autoStore property is set in the team configuration, those credentials will be automatically securely stored, and the user will not be prompted in the future.
Locating your team configuration values
Our recommendations place much of the effort to create a workable configuration on a trailblazer for the team.
As mentioned earlier, the trailblazer may have created a global configuration file and other per-project configurations. Several of those configurations may be simultaneously in-effect for the directory in which you issue your Zowe command. If you run a Zowe command and do not get the results that you expect, you must determine what might be incorrectly configured. An incorrect configuration can occur when you forget about a global configuration or a user configuration which is overridden by a project configuration.
While the documents cited earlier in this article describe how those combinations work, several tools exist to help identify which of your existing configuration files are used by your Zowe command and which properties from those configurations will be used by the command.
Which team configuration files affect my Zowe command ?
To identify if any team configuration files are found, and if so which ones, issue the following command:
-> zowe config list --locations --root
C:\Your\project\zowe.config.user.json
C:\Your\project\zowe.config.json
C:\Users\YourUserId\.zowe\zowe.config.jsonIn this example, a project user configuration exists, a project team configuration exists, and a global team configuration exists. Properties in files higher in the list will override properties from files lower in the list. If you placed a desired property value in your global configuration file, you should confirm that the property was not overridden by a project configuration file.
If you receive no output from this command, then no team configuration file was found.
Show property values used by a Zowe command
If your Zowe command fails to properly connect to your desired service, but you think that you placed the right values in the right configuration files, you can show all of the connection property values that the command would use without actually running the command. You enter your normal Zowe command and add the option “- -show-inputs-only”.
-> zowe zos-files list data-set "SYS1.PARMLIB*" --show-inputs-only
Some inputs are not displayed:
Inputs below may be displayed as '(secure value)'. Properties identified as
secure fields are not displayed by default.
Set the environment variable ZOWE_SHOW_SECURE_ARGS to 'true' to display secure
values in plain text.
commandValues:
host: YourHost.YourCompany.com
port: 443
user: (secure value)
password: (secure value)
reject-unauthorized: false
protocol: https
show-inputs-only: true
profileVersion: v2
optionalProfiles:
- zosmf
- base
locations:
- C:\Users\YourUserId\.zowe\zowe.config.jsonIn the example above, if your site does not run the z/OSMF service on port 443, you have identified that there is some mistake in your configuration that you must fix.
If you cannot remember whether you reset your password in your Zowe configuration after a corporate-required password change, you can use the ZOWE_SHOW_SECURE_ARGS environment variable (mentioned in the text of the example above) to see the actual values of your secured credentials.
Show the gory details of configured property values
After the earlier techniques identify which items are wrong, you can typically use an editor on each of your configuration files to see which configuration file has an unwanted value that overrides a desired value.
Should you struggle finding the culprit by editing multiple files, another Zowe command can display every property from every configuration file.
-> zowe config list --locations
C:\Your\project\zowe.config.user.json
$schema: ./zowe.schema.json
profiles:
MyUserBaseProf:
type: base
properties:
user: (secure value)
password: (secure value)
rejectUnauthorized: false
defaults:
base: MyUserBaseProf
C:\Your\project\zowe.config.json
$schema: ./zowe.schema.json
profiles:
Host1Prof:
type: zosmf
properties:
host: YourHost1.YourCompany.com
port: 443
responseFormatHeader: true
C:\Users\YourUserId\.zowe\zowe.config.json
Host2Prof:
type: zosmf
properties:
host: YourHost2.YourCompany.com
port: 4433
responseFormatHeader: true
profiles:
tso_ca11:
type: tso
properties:
account: 123456789
characterSet: 697
codePage: 1047
columns: 80
logonProcedure: IZUFPROC
regionSize: 4096
rows: 24
... Lots of stuff ommitted ...The command above lists:
- Every configuration file that will be used by a Zowe command in the current directory.
- Every property name and value from each of those configuration files.
That command generates a lot of output. The example above only shows a selected snippet of the total output. You may want to redirect the output of this command into a file and view that file in a text editor.
Sharing plugins with your entire team
We have identified ways to create, debug, and share a team configuration with your entire team. Those techniques can save your teammates a lot of time. However, many sites add Zowe CLI plugins to gain added functionality needed for their operations. Examples include plugins for CICS, DB2, IMS, and MQ, just to name a few.
By default, the “zowe plugins install” command will install a plugin into a directory under the user’s HOME directory, which means all files under that directory are specific to that user. Most of the files created by Zowe CLI should be specific to a given user. However, some sites may not want plugins to be specific to every user.
An organization may want to limit which plugins are used. It may want to ensure that everyone uses the same version of every plugin. It may want to avoid making every user in the organization install every needed plugin.
You can set the environment variable ZOWE_CLI_PLUGINS_DIR to a directory path into which plugins should be installed. If your site utilizes shared network directories, your trailblazer could point to a directory under one of those network directories. The trailblazer can install every desired plugin. Every other user can set the ZOWE_CLI_PLUGINS_DIR environment variable to the same network directory. Those users will then be able to use the plugins without having to install them. Future plugin updates could also be performed once for every user to share.
A similar approach could be used by organizations which utilize a virtual desktop technology to provide a working environment for their users. The plugins could be installed into a common directory within the virtual desktop image, and the ZOWE_CLI_PLUGINS_DIR variable would point to that common directory.
You do not modify a schema file, but the installation of a plugin does
As mentioned earlier, the “zowe config init” command will create a zowe.schema.json file, which is used to provide IntelliSense-like assistance in your text editor. The schema contains characteristics for built-in Zowe commands and for every plugin installed at the time that you run “zowe config init”.
Each time you install (or re-install) a plugin, the schema file is updated by the “zowe plugins install” command to contain the latest characteristics of that newly installed plugin. If a trailblazer is sharing a team configuration with their team and managing the set of plugins for the team, the schema file should also always be shared with the team. Each time the trailblazer installs a plugin, the updated schema should again be shared with the team.
The act of uninstalling a plugin does NOT remove any characteristics from the schema file. Because this is somewhat of a destructive act, we chose not to remove any plugin information from the schema file. Keep in mind, that when uninstalling a plugin, no profiles are removed from your team configuration file. By leaving the schema file intact, users will still be able to see IntelliSense hints on those profiles (which remain in their team configuration) related to any uninstalled plugin.
If you install or uninstall a plugin while the Zowe CLI daemon is running, remember to restart the daemon. As described in the Zowe documentation topic “Restart daemon mode”, a running daemon will not recognize changes to plugins until the daemon is restarted.
Installing Zowe CLI into a custom location
The location into which NPM installs packages (including Zowe CLI) can be problematic for some sites that operate in a restricted environment. While the installation operation is not within the control of Zowe CLI, you can use techniques to persuade NPM to place Zowe CLI into a more desirable location.
The default location into which NPM installs packages on Windows is %AppData%\npm. NPM documents the default installation location for Windows and Linux here: npm Docs -> Configuring npm -> Folders
This default location may be undesirable for some sites. Your site may have security restrictions that prevent files from being installed to the default NPM installation directory. It may have restrictions preventing programs from being loaded from the default NPM installation directory. Such situations are show-stopping roadblocks. If Zowe CLI were to be installed in a directory that was not restricted, you would avoid these problems.
The following conditions can also conspire to make the Zowe CLI impractical for use from the default NPM installation directory.
- You use network directories with a virtual machine server.
- The default NPM installation directory is under a network directory that is extremely remote (as in across the ocean) from your virtual machine location.
While Zowe CLI does function in such an environment, commands can take 15 to 30 seconds to complete because of delays loading all of the Zowe CLI program modules across that long-distance network connection. If Zowe CLI were to be installed into a local directory (or at least a closer network directory) you would avoid the performance degradation.
To address problems like those above, you set the NPM “prefix” to override NPM’s default installation directory. Detailed documentation exists in these locations:
The following example changes NPM’s default installation directory and then does a standard NPM install command to install Zowe CLI into that new location.
-> npm config set prefix C:\Your\Desired\Directory
-> npm install -g @zowe\cliFrom this point forward, all normal, global NPM install commands will place apps under C:\Your\Desired\Directory until you set the prefix again.
Keep in mind that if you have security access restrictions or network latency on some of your directories, you may also experience difficulties with other Zowe CLI files (like log files, global configuration files, etc) or with plugin programs. Fortunately, Zowe CLI is in control of those items. You can alter the location of those items with the ZOWE environment variables ZOWE_CLI_HOME and ZOWE_CLI_PLUGINS_DIR.
Summary
Zowe V1 LTS gave thousands of Zowe CLI consumers an opportunity to experience a remote CLI to the mainframe for the first time ever. Many provided feedback that helped the Zowe CLI team understand specific challenges and policies governing desktop installation and organizational rollout. As a result, we prioritized capabilities related to installation & configuration and delivered them in Zowe V2 LTS. In this article we shared our recommendations for improving the on-boarding experience while overcoming site-specific restrictions. You may not need every technique, but it is very likely that you can benefit from a few.
Finding out more
If you enjoyed this blog checkout more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #zowe-cli or #zowe-onboarding. If this is your first time using the Open Mainframe Slack Channel register here.
Zowe is owned and managed by the Open Mainframe Project which is a Linux Foundation project.
