Table of Contents:
- Feature overview
- Installing CLI V2 version
- Initializing team configuration
- (Optional) Initializing user-specific configuration
- Editing configuration
- Managing credential security
- Tips for efficient configuration
- Sharing team configuration
- Example configurations
In the V1-LTS version of the CLI, users issue commands from the zowe profiles group to create, edit, and manage user profiles. Each profile contains the host, port, username, and password for a specific mainframe service instance. While that approach is effective, users often need to duplicate values across profiles and spend time managing many profiles separately.
The team profile functionality simplifies profile management by letting you edit, store, and share mainframe configuration details in one location. You can use a text editor to populate configuration files with connection details for your mainframe services.
Team profile configuration can improve your Zowe CLI experience in the following ways:
- As a CLI user, you can manage your connection details efficiently in one location.
- As a team leader, you can share a configuration file with your team members so that they can easily access mainframe services. You can add the file directly to your project in an SCM.
- As a new team member, you can onboard quickly by consuming your team's configuration file.
In this version, Secure Credential Store (SCS) Plug-in is deprecated. The zowe scs and zowe config command groups are obsolete. The equivalent functionality that encrypts your credentials is now included in the core CLI.
With the new configuration, the CLI prompts you to enter username and password securely by default. Commands in the new zowe config command group let you manage security for any option value.
To get started, install the Zowe CLI V2 LTS version from the online registry. You can follow this procedure for a first-time installation, or to update a currently installed version.
Follow these steps:
-
Meet the software requirements for Zowe CLI.
-
To install or update the core CLI, open a command-line window and issue the following command:
npm install -g @zowe/cli@zowe-v2-lts -
Meet the software requirements for each plug-in.
-
(Optional) Check npmjs.com for any Zowe plug-ins that have a V2 LTS version available. If an V2 version is available, you can issue the following command (substituting the plugin name) to install it. If no V2 version exists, try installing the
@latestversion of the plug-in:zowe plugins install @zowe/<plugin-name>@zowe-v2-ltsZowe CLI and optional plug-ins are installed!
-
Open a command-line window and issue the following command:
zowe scs revert --force -
If you previously had the Secure Credential Store plug-in installed, uninstall it now to avoid unexpected behavior. Issue the following command:
zowe plugins uninstall @zowe/secure-credential-store-for-zowe-cli -
If you previously had an instance of Zowe CLI installed, your current configuration files are ignored if zowe.config.json is found globally, at the project level, or up the directory structure. Delete the following files from your local
.zowe/directory:.zowe/settings/imperative.json.zowe/profiles
Important! Prior to deleting the contents of the
/profilesdirectory, take note of any mainframe service details that you need (host, port, etc...). You might want to save the entire/profilesdirectory to another location on your computer so that you can reference or restore the profiles later.
You can now configure the CLI and issue commands.
To begin, define a connection to z/OSMF and initialize your configuration files. We recommend this method for getting started, but you can choose create the configuration files manually if desired.
Follow these steps:
-
Issue the following command:
zowe config init --global-configThe CLI provides a series of prompts.
-
Respond to the prompts to enter a username and password for a mainframe service such as z/OSMF. The
config initcommand ensures that your credentials are stored securely on your computer by default.After you respond to the prompts, the following file is added to your local
.zowedirectory:zowe.config.json- A team configuration file. This is the primary location where your MF service connection details such as host and port are defined. Use this configuration file for the following procedures.
-
Edit the zowe.config.json file to change the name of the LPAR, to supply a value for the host name, and to change the port number if needed.
-
Issue a Zowe CLI command to test that you can access z/OSMF. For example, list all data sets under your user ID:
zowe zos-files list data-set "MY.DATASET.*"A list of data sets is returned. You successfully configured Zowe CLI to access a z/OSMF instance!
If the CLI returns an error message, verify that you have access to the target system. Examine your configuration files in a text editor to verify that the information you entered is correct.
Important!: After the configuration files are in place (either via the zowe config init command or by manually creating the files), the old zowe profiles commands will no longer function. Expect to see errors if you attempt to make use of old profiles.
Additionally, you can generate a user-specific configuration file. In your user config, you can override values that are defined in the team zowe.config.json.
Issue the command zowe config init --global-config or zowe config init --gc to create the global (zowe.config.json) and zowe config init --global-config --user-config or zowe config init --gc --uc to generate the user (zowe.config.user.json) config files.
In your user-specific file, notice that the top level defaults and secure fields are empty. The profiles do not have any properties. You can add your connection details as properties here to override properties in zowe.config.json, or add add new connections.
After the initial setup, you can define additional mainframe services to your team or user config.
Open the ~/.zowe/zowe.config.json file in a text editor or IDE on your computer. The profiles object should contain connection and other frequently needed information for accessing various services. For example:
{
"$schema": "./zowe.schema.json",
"profiles": {
"lpar1": {
"properties": {
"host": "example1.com"
},
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"port": 443
}
}
},
"secure": [
"user",
"password"
]
}
},
"defaults": {
"zosmf": "lpar1.zosmf"
},
"autoStore": true
}From here, you can edit the details as needed and save the file. For example, you might change the host or port fields if those values changed.
To add a new service, for example add a new instance of z/OSMF that runs on a different mainframe LPAR, you can build on the existing array as follows:
{
"$schema": "./zowe.schema.json",
"profiles": {
"lpar1": {
"properties": {
"host": "example1.com"
},
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"port": 443
}
}
},
"secure": [
"user",
"password"
]
},
"lpar2": {
"properties": {
"host": "example2.com"
},
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"port": 1443
}
}
},
"secure": [
// See below about tips for using base array to avoid duplicating these
"user",
"password"
]
}
},
"defaults": {
// Change to lpar2.zosmf if you wish to change default profile
"zosmf": "lpar1.zosmf"
},
"autoStore": true
}You can continue to add more LPARs, and more services within each LPAR. After you make changes, save the file and issue a Zowe CLI command to the service to verify connection.
When you first run the zowe config init --global-config command, the profiles.base.properties.user and profiles.base.properties.password fields are defined to the "secure" array in your configuration file. This ensures that username and password are stored securely on your computer.
Issue the zowe config secure command to re-prompt for all secure fields when you want to update them (for example, when you want to change your username and password).
To secure a specific field, use the command zowe config set --secure <property-path>. For example, you can issue zowe config set --secure profiles.base.properties.password. If you issue the command for an option that is already secure, the CLI re-prompts you to enter a new option value.
Alternatively, you can use an editor to define options to the secure array in zowe.config.json manually. Any option that you define to there becomes secure/prompted-for.
There are several methods you can employ to more efficiently update and maintain your configuration.
Zowe CLI uses a "command option order of precedence" that lets your service definitions inherit option values. You can use this to your advantage, because it lets you avoid duplicating the same option value in several places.
The CLI checks for option values in the following order. If not found, the next location is checked:
- Options you define explicitly on the command-line
- Environment variables
- Service type profiles
- Base type profiles
- If no value is found, the default value for the option is used.
The user name and password fields are not supplied in the service definitions.
In the following example, the username and password fields for ZOSMF1 and ZOSMF2 are user name and password fields are not supplied in the service definitions to allow them to inherit values from the base array:
{
"$schema": "./zowe.schema.json",
"profiles": {
"lpar1": {
"properties": {
"host": "example1.com"
},
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"port": 443
}
}
}
},
"lpar2": {
"properties": {
"host": "example2.com"
},
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"port": 1443
}
}
}
},
"my_base": {
"type": "base",
"properties": {
"rejectUnauthorized": true
},
"secure": [
"user",
"password"
]
}
},
"defaults": {
"zosmf": "lpar1.zosmf",
"base": "my_base"
},
"autoStore": true
}The base array is a useful tool for sharing option values between services. You might define options to the base array in the following situations:
- You have multiple services that share the same username, password, or other value.
- You want to store a web token to access all services through Zowe API Mediation Layer.
- You want to trust a known self-signed certificate, or your site does not have server certificates configured. You can define
reject-unauthorizedin the base array with a value offalseto apply to all services. Understand the security implications of accepting self-signed certificates at your site before you use this method.
You might want to share configuration in the following scenarios:
- Share team config with developers so that they can begin working with a defined set of mainframe services. The recipient of the file manually places it in their local
~/.zowefolder before issuing CLI commands. - Add team config to your project directory in an SCM tool such as GitHub. This lets other developers pull the project to their local machine and make use of the defined configuration. Zowe CLI commands that you issue from within the project directory automatically use the project's config scheme.
- Enable test automation and CI/CD, letting your pipelines make use of the project configuration.
In this example configuration, the settings are accessing multiple services directly on multiple LPARs that share the same username and password.
{
"$schema": "./zowe.schema.json",
"profiles": {
"lpar1": {
"properties": {
"host": "example1.com"
},
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"port": 443
}
},
"tso": {
"type": "tso",
"properties": {
"account": "ACCT#",
"codePage": "1047",
"logonProcedure": "IZUFPROC"
}
},
"ssh": {
"type": "ssh",
"properties": {
"port": 22
}
}
}
},
"lpar2": {
"properties": {
"host": "example2.com"
},
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"port": 1443
}
}
}
},
"my_base": {
"type": "base",
"properties": {
"rejectUnauthorized": true
},
"secure": [
"user",
"password"
]
}
},
"defaults": {
"zosmf": "lpar2.zosmf",
"tso": "lpar1.tso",
"ssh": "lpar1.ssh",
"base": "my_base"
},
"autoStore": true
}In this example configuration, the settings are accessing multiple services via the API ML (where MFA/SSO is achievable via token-based authorization).
{
"$schema": "./zowe.schema.json",
"profiles": {
"lpar1": {
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"basePath": "api/v1"
}
},
"cics": {
"type": "cics",
"properties": {
"basePath": "api/v1/my_cics"
}
},
"db2": {
"type": "db2",
"properties": {
"basePath": "api/v1/my_db2"
}
}
}
},
"my_base": {
"type": "base",
"properties": {
"host": "example1.com",
"port": 443,
"rejectUnauthorized": true,
"tokenType": "apimlAuthenticationToken"
},
"secure": [
"tokenValue"
]
}
},
"defaults": {
"zosmf": "lpar1.zosmf",
"cics": "lpar1.cics",
"db2": "lpar1.db2",
"base": "my_base"
},
"autoStore": true
}In this example configuration, the settings are accessing multiple services directly on LPAR1 and LPAR2 where username and password varies between the LPAR1 and LPAR2 services. This example is identical to first example except that LPAR1 and LPAR2 each contain a secure array, instead of just one secure array in the "my_base" profile.
{
"$schema": "./zowe.schema.json",
"profiles": {
"lpar1": {
"properties": {
"host": "example1.com"
},
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"port": 443
}
},
"tso": {
"type": "tso",
"properties": {
"account": "ACCT#",
"codePage": "1047",
"logonProcedure": "IZUFPROC"
}
},
"ssh": {
"type": "ssh",
"properties": {
"port": 22
}
}
},
"secure": [
"user",
"password"
]
},
"lpar2": {
"properties": {
"host": "example2.com"
},
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"port": 1443
}
}
},
"secure": [
"user",
"password"
]
},
"my_base": {
"type": "base",
"properties": {
"rejectUnauthorized": true
}
}
},
"defaults": {
"zosmf": "lpar2.zosmf",
"tso": "lpar1.tso",
"ssh": "lpar1.ssh",
"base": "my_base"
},
"autoStore": true
}In this example configuration, API ML is leveraged to access production services but services on a dev-test environment can be accessed directly.
{
"$schema": "./zowe.schema.json",
"profiles": {
"prod": {
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"basePath": "api/v1"
}
},
"cics": {
"type": "cics",
"properties": {
"basePath": "api/v1/my_cics"
}
},
"db2": {
"type": "db2",
"properties": {
"basePath": "api/v1/my_db2"
}
}
}
},
"dev": {
"properties": {
"host": "example1.com"
},
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"port": 443
}
},
"tso": {
"type": "tso",
"properties": {
"account": "ACCT#",
"codePage": "1047",
"logonProcedure": "IZUFPROC"
}
},
"ssh": {
"type": "ssh",
"properties": {
"port": 22
}
}
},
"secure": [
"user",
"password"
]
},
"my_base": {
"type": "base",
"properties": {
"host": "example1.com",
"port": 443,
"rejectUnauthorized": true,
"tokenType": "apimlAuthenticationToken"
},
"secure": [
"tokenValue"
]
}
},
"defaults": {
"zosmf": "prod.zosmf",
"cics": "prod.cics",
"db2": "prod.db2",
"tso": "dev.tso",
"ssh": "dev.ssh",
"base": "my_base"
},
"autoStore": true
}