Using Global Profile Configuration (Technical Preview)
PDF
Open doc issue
Twitter
LinkedIn
Facebook
EmailUsing Global Profile Configuration (Technical Preview)
If you already installed the supported version @zowe-v1-lts, switch versions to try this feature. Global profiles will be included in the next major Zowe release, V2.0.0-LTS. You can also install the @next release of Zowe CLI.
Table of Contents:
- Feature overview
- Initializing global configuration
- Initializing user-specific configuration (Optional)
- Editing global configuration
- Managing credential security
- Tips for efficient configuration
- Sharing global configuration
- Example configurations
Feature overview#
In the V1-LTS version of Zowe 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 one mainframe service instance. While effective, users often need to duplicate values across profiles and spend time managing many profiles.
The introduction of global profiles simplifies profile management by letting you edit, store, and share mainframe configuration details in one location. You can use a text editor to populate global profiles with connection details for your mainframe services.
Benefits#
Global profiles improve your Zowe CLI experience:
- As a user, you can manage your connection details efficiently in one location.
- As a team leader, you can share global profiles 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 using your team's configuration file.
Changes to secure credential storage#
With the introduction of global profiles, the Secure Credential Store (SCS) Plug-in is deprecated in the @next version. The zowe scs and zowe config command groups are obsolete. Secure credential encryption is now included in the core CLI.
The CLI prompts you to enter the username and password securely by default. Commands in the zowe config command group let you manage security for any option value.
Initializing global configuration#
Verify that you have installed the @next release of Zowe CLI.
You have two options to initialize the global configuration:
- Define a connection to z/OSMF (recommended).
- Create your configuration files manually.
Follow these steps:
Issue the command:
zowe config init --global-configThe CLI responds with prompts for a username and password.
Respond to the prompts with a username and password for a mainframe service such as z/OSMF.
Note: The
config initcommand ensures that your credentials are stored securely on your computer by default.After you respond, the
zowe.config.jsonglobal configuration file is added to your local.zowedirectory. 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.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 now-deprecated zowe profiles commands will no longer function. Zowe CLI will return errors if you attempt to use deprecated profile commands.
Initializing user-specific configuration (Optional)#
You can generate a user-specific configuration file that overrides the values defined in the global zowe.config.json file.
To generate both global (zowe.config.json) and user (zowe.config.user.json) config files, issue the command zowe config init --global-config --user-config.
In your user-specific file, notice that the "defaults" object is empty and 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.
Editing global configuration#
After the initial setup, you can define additional mainframe services to the global (or user-specific) configuration file.
Open the ~/.zowe/zowe.config.json file in a text editor or IDE on your computer. The profiles object contains connection and other frequently needed information for accessing various services. For example:
{ "$schema": "./zowe.schema.json", "profiles": { "zosmf": { "type": "zosmf", "properties": { "port": 443 } }, "base": { "type": "base", "properties": { "host": "example1.com" }, "secure": [ "user", "password" ] } }, "defaults": { "zosmf": "zosmf", "base": "base" },}You can edit the details as needed and save the file.
For example, to add a new instance of z/OSMF that runs on a different mainframe LPAR, you can build on the existing config as follows:
{ "$schema": "./zowe.schema.json", "profiles": { "zosmf_lpar1": { "type": "zosmf", "properties": { "port": 443 } }, "zosmf_lpar2": { "type": "cics", "properties": { "host": "example2.com", "port": 1443 }, "secure": [ // This secure array isn't needed if user and password are same as for LPAR1 "user", "password" ] }, "base": { "type": "base", "properties": { "host": "example1.com" }, "secure": [ "user", "password" ] } }, "defaults": { // Change to zosmf_lpar2 if you wish to change default profile "zosmf": "zosmf_lpar1", "base": "base" }}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 the connection.
Managing credential security#
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 the username and password are stored securely on your computer.
To update the secure fields (for example, when you want to change your username and password), issue the zowe config secure command.
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 secured, the CLI prompts you to enter a new option value.
You can use an editor to define options to the secure array in zowe.config.json. Any option that you define to there becomes secure/prompted-for.
Tips for efficient configuration#
There are several methods to more efficiently update and maintain your configuration:
- Leverage the command option order of precedence
- Utilize a base profile or nested profiles
Command option order of precedence#
Zowe CLI uses a command option order of precedence by which service definitions inherit option values. Use this feature to avoid duplicating option values.
Zowe CLI checks for option values in order, skipping null values:
- Explicit command-line option values
- Environment variables
- Service type profiles
- Base type profiles
- Default option value
In the example config above, the host, user, and password fields are not supplied in the service profile for "zosmf_lpar1", because they inherit values from the base profile.
Tips for using the base profile#
Use the base profile to share option values between services. You might share option values between services 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 profile 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.
If you have multiple LPARs and want to share option values only between services that run on the same LPAR, you can use nested profiles to achieve this (see Example 1 below).
Sharing global configuration#
You might want to share a configuration globally:
- 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. - To add 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.
- To enable test automation and CI/CD, letting your pipelines make use of the project configuration.
Example configurations#
Example 1: The settings are using nested profiles to access 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 } } } }, "base": { "type": "base", "properties": { "rejectUnauthorized": true }, "secure": [ "user", "password" ] } }, "defaults": { "zosmf": "lpar2.zosmf", "tso": "lpar1.tso", "ssh": "lpar1.ssh", "base": "base" }}Example 2: The settings are accessing multiple services using the API ML (where MFA/SSO is achievable via token-based authorization).
{ "$schema": "./zowe.schema.json", "profiles": { "zosmf": { "type": "zosmf", "properties": { "basePath": "api/v1" } }, "cics": { "type": "cics", "properties": { "basePath": "api/v1/cics" } }, "db2": { "type": "db2", "properties": { "basePath": "api/v1/db2" } }, "base": { "type": "base", "properties": { "host": "example.com", "port": 443, "rejectUnauthorized": true, "tokenType": "apimlAuthenticationToken" }, "secure": [ "tokenValue" ] } }, "defaults": { "zosmf": "zosmf", "cics": "cics", "db2": "db2", "base": "base" }}Example 3: 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 Example 1 except that LPAR1 and LPAR2 each contain a secure array, instead of just one secure array in the "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" ] }, "base": { "type": "base", "properties": { "rejectUnauthorized": true } } }, "defaults": { "zosmf": "lpar2.zosmf", "tso": "lpar1.tso", "ssh": "lpar1.ssh", "base": "base" }}Example 4: Using API ML to access production services while 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/cics" } }, "db2": { "type": "db2", "properties": { "basePath": "api/v1/db2" } } } }, "dev": { "properties": { "host": "example2.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" ] }, "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": "base" }}