From 45bc6f5ed3d8ae0ebffbea187f2d8c41147cbc27 Mon Sep 17 00:00:00 2001 From: Leanid Astrakou Date: Fri, 4 Mar 2022 17:04:28 -0500 Subject: [PATCH 01/17] WIP changes to App server Advanced configuration for V2 Signed-off-by: Leanid Astrakou --- docs/extend/extend-desktop/mvd-logutility.md | 9 +- docs/user-guide/mvd-configuration.md | 200 ++++++++++--------- 2 files changed, 105 insertions(+), 104 deletions(-) diff --git a/docs/extend/extend-desktop/mvd-logutility.md b/docs/extend/extend-desktop/mvd-logutility.md index 7700d632c4..07308f06d7 100644 --- a/docs/extend/extend-desktop/mvd-logutility.md +++ b/docs/extend/extend-desktop/mvd-logutility.md @@ -45,7 +45,9 @@ NodeJS uses `global` as its global object, so the logger is attached to: #### Web -Browsers use `window` as the global object, so the logger is attached to: +(Angular App Instance Injectible). See **Logger** in [Zowe Desktop and window management](mvd-desktopandwindowmgt.md). + +(others) Browsers use `window` as the global object, so the logger is attached to: `window.COM_RS_COMMON_LOGGER` ### Component logger @@ -57,11 +59,6 @@ Component loggers are created from the core logger object, but when working with See **Router Dataservice Context** in the topic [Dataservices](mvd-dataservices.md). -#### Web - -(Angular App Instance Injectible). See **Logger** in [Zowe Desktop and window management](mvd-desktopandwindowmgt.md). - - ## Logger API The following constants and functions are available on the central logging object. diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 4905f336a0..b8a4faedcb 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -1,11 +1,11 @@ # Configuring Zowe Application Framework -After you install Zowe™, you can optionally configure the Zowe Application Framework as a Mediation Layer client, configure connections for the terminal application plug-ins, or modify the Zowe Application Server and Zowe System Services (ZSS) configuration, as needed. +After you install Zowe™, you can optionally configure the Zowe Application Framework as a Mediation Layer client, configure connections for the terminal application plugins, or modify the Zowe Application Server and Zowe System Services (ZSS) configuration, as needed. ## Configuring the framework as a Mediation Layer client For simpler Zowe administration and better security, you can install an instance of the Zowe Application Framework as an API Mediation Layer client. -This configuration is simpler to administer because the framework servers are accessible externally through a single port. It is more secure because you can implement stricter browser security policies for accessing cross-origin content. +This configuration is simpler to administer because the framework servers are accessible externally through a single port: API ML Gateway port. It is more secure because you can implement stricter browser security policies for accessing cross-origin content. You must use SSL certificates to configure the Zowe Application Server to communicate with the SSL-enabled Mediation Layer. Those certificates were created during the Zowe installation process, and are located in the `$RUNTIME_DIR/components/app-server/share/zlux-app-server/defaults/serverConfig` directory. @@ -17,23 +17,22 @@ For earlier releases, you must register the Application Server with the Mediatio ### Accessing the Application Server -**Note:** Before Accessing the Application Server, first [create and configure the Zowe instance directory](configure-instance-directory.md). +**Note:** Before Accessing the Application Server, first [first install and configure the Zowe instance](configure-instance-directory.md). To access the Application Server through the Mediation Layer, use the Mediation Layer gateway server hostname and port. For example, when accessed directly, this is Zowe Desktop URL: `https:///ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` -The port number for the Zowe Desktop is the value of the `ZOWE_ZLUX_SERVER_HTTPS_PORT` variable in the `instance.env` file in the instance directory, see [Creating and configuring the Zowe instance directory](configure-instance-directory.md). +The port number for the Zowe Desktop is the value of the `components.app-server.port` variable in the `zowe.yaml` file in the instance directory, see [Creating and configuring the Zowe instance directory](configure-instance-directory.md). When accessed through the API Mediation Layer, this is the Zowe Desktop URL: -`https:///ui/v1/zlux/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` +`https:///zlux/ui/v1/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` -The port number for the API Mediation Layer is the value of the `GATEWAY_PORT` variable in the `instance.env` file in the instance directory. +The port number for the API Mediation Layer is the value of the `components.gateway.port` variable in the `zowe.yaml` file in the instance directory. +## Setting up terminal application plugins -## Setting up terminal application plug-ins +Follow these optional steps to configure the default connection to open for the terminal application plugins. -Follow these optional steps to configure the default connection to open for the terminal application plug-ins. - -### Setting up the TN3270 mainframe terminal application plug-in +### Setting up the TN3270 mainframe terminal application plugin `_defaultTN3270.json` is a file in `tn3270-ng2/`, which is deployed during setup. Within this file, you can specify the following parameters to configure the terminal connection: ``` @@ -43,7 +42,7 @@ Follow these optional steps to configure the default connection to open for the type: <"telnet" or "tls"> } ``` -### Setting up the VT Terminal application plug-in +### Setting up the VT Terminal application plugin `_defaultVT.json` is a file in `vt-ng2/`, which is deployed during setup. Within this file, you can specify the following parameters to configure the terminal connection: ``` @@ -58,15 +57,18 @@ Follow these optional steps to configure the default connection to open for the The Zowe App Server and ZSS rely on many required or optional parameters to run, which includes setting up networking, deployment directories, plugin locations, and more. -For convenience, the Zowe Application Server and ZSS read from a JSON file with a common structure. ZSS reads this file directly as a startup argument, while the Zowe Application Server (as defined in the `zlux-server-framework` repository) accepts several parameters. The parameters are intended to be read from a JSON file through an implementer of the server, such as the example in the `zlux-app-server` repository (the `lib/zluxServer.js` file). The file accepts a JSON file that specifies most, if not all, of the parameters needed. Other parameters can be provided through flags, if needed. - -For an instance, the configuration file is located at and can be edited at `$INSTANCE_DIR/workspace/app-server/serverConfig/server.json`. The defaults from which that file is generated are located at `$RUNTIME_DIR/components/app-server/share/zlux-app-server/defaults/serverConfig/server.json` +For convenience, the Zowe Application Server and ZSS read from the `zowe.yaml` file with a common structure, i.e. `components.app-server` and `components.zss`. +ZSS reads this file directly as a startup argument, while the Zowe Application Server (as defined in the `zlux-server-framework` repository) accepts several parameters. The parameters are intended to be read from a JSON file through an implementer of the server, such as the example in the `zlux-app-server` repository (the `lib/zluxServer.js` file). The file accepts a JSON file that specifies most, if not all, of the parameters needed. Other parameters can be provided through flags, if needed. **Note:** All examples are based on the *zlux-app-server* repository defaults. +## Environment variables + +In Zowe V1, environment variables were originally specified in `instance.env`. In V2, while most variables can be customized in corresponding component sections of `zowe.yaml`, additional enviornment variables can be specified in `zowe.environments` section. + ## Network configuration -**Note:** The following attributes are to be defined in the server's JSON configuration file. +**Note:** The following attributes are to be defined in the `zowe.yaml` file. The App Server can be accessed over HTTP and/or HTTPS, provided it has been configured for either. @@ -138,35 +140,32 @@ These directories dictate where the [Configuration Dataservice](https://github.c ``` ### Old defaults -Prior to Zowe release 1.8.0, the location of the configuration directories were initialized to be within the `zlux-app-server` folder unless otherwise customized. 1.8.0 has backwards compatibility for the existence of these directories, but they can and should be migrated to take advantage of future enhancements. +Prior to Zowe release 2.0.0, the location of the configuration directories were initialized to be within the `` folder unless otherwise customized. 2.0.0 does have backwards compatibility for the existence of these directories, but `` folder no longer exists, so they should be migrated to new locations. | Folder | New Location | Old Location | Note |--------|--------------|--------------|----- -| productDir | zlux-app-server/defaults | zlux-app-server/deploy/product | Official installs place zlux-app-server within /components/app-server/share -| siteDir | /workspace/app-server/site | zlux-app-server/deploy/site | INSTANCE_DIR is ~/.zowe if not otherwise defined. Site is placed within instance due to lack of SITE_DIR as of 1.8 -| instanceDir | /workspace/app-server | zlux-app-server/deploy/instance | -| groupsDir | /workspace/app-server/groups | zlux-app-server/deploy/instance/groups | -| usersDir | /workspace/app-server/users | zlux-app-server/deploy/instance/users | -| pluginsDir | /workspace/app-server/plugins | zlux-app-server/deploy/instance/ZLUX/plugins | Defaults located at zlux-app-server/defaults/plugins, previously at zlux-app-server/plugins +| siteDir | zlux-app-server/deploy/site | /workspace/app-server/site | +| instanceDir | zlux-app-server/deploy/instance | /workspace/app-server | +| groupsDir | zlux-app-server/deploy/instance/groups | /workspace/app-server/groups | +| usersDir | zlux-app-server/deploy/instance/users | /workspace/app-server/users | +| pluginsDir | zlux-app-server/deploy/instance/ZLUX/plugins | /workspace/app-server/plugins | Defaults located at zlux-app-server/defaults/plugins -## Application plug-in configuration +## Application plugin configuration -This topic describes application plug-ins that are defined in advance. +This topic describes application plugins that are defined in advance. -In the configuration file, you can specify a directory that contains JSON files, which tell the server what application plug-in to include and where to find it on disk. The backend of these application plug-ins use the server's plug-in structure, so much of the server-side references to application plug-ins use the term *plug-in*. +In the configuration file, you can specify a directory that contains JSON files, which tell the server what application plugin to include and where to find it on disk. The backend of these application plugins use the server's plugin structure, therefore much of the server-side references to application plugins use the term *plugin*. -To include application plug-ins, define the location of the plug-ins directory in the configuration file, through the top-level attribute **pluginsDir**. +To include application plugins, define the location of the plugins directory in the `zowe.yaml` file, via *zowe.extensionDirectory* variable. -**Note:** In this example, the directory for these JSON files is the Application Server defaults. However, in an instance of Zowe it is best to provide a folder unique to that instance - usually `$INSTANCE_DIR/workspace/app-server/plugins`. - -### Plug-ins directory example +### Plugins directory example ``` -// All paths relative to zlux-app-server/lib -// In real installations, these values will be configured during the install process. +// All paths should be absolute //... - "pluginsDir":"../defaults/plugins", + # Where extensions are installed + extensionDirectory: /your-user/zowe/extensions ``` ## Logging configuration @@ -175,24 +174,26 @@ For more information, see [Logging Utility](../extend/extend-desktop/mvd-logutil ## ZSS configuration -Running ZSS requires a JSON configuration file that is similar or the same as the one used for the Zowe Application Server. The attributes that are needed for ZSS, at minimum, are:*productDir*, *siteDir*, *instanceDir*, *groupsDir*, *usersDir*, *pluginsDir* and *agent.http.port*. All of these attributes have the same meaning as described above for the server, but if the Zowe Application Server and ZSS are not run from the same location, then these directories can be different. +Running ZSS requires a `zowe.yaml` configuration that is similar to the one used for the Zowe Application Server. The attributes that are needed for ZSS (*components.zss*) at minimum, are: *port*, *crossMemoryServerName*. -Attributes that control ZSS are in the agent object. For example, *agent.http.port* is the TCP port that ZSS will listen on to be contacted by the App Server. Define this in the configuration file as a value between 1024-65535. Similarly, if specified, *agent.http.ipAddresses* will be used to determine which IP addresses the server should bind to. Only the first value of the array is used. It can either be a hostname or an ipv4 address. +For example, *port* is the TCP port that ZSS will listen on to be contacted by the App Server. Define this in the configuration file as a value between 1024-65535. Similarly, if specified, *agent.http.ipAddresses* will be used to determine which IP addresses the server should bind to (note: Should only be used with AT-TLS and is not secure, otherwise use HTTPS). Only the first value of the array is used. It can either be a hostname or an IPv4 address. Example of the agent body: ``` - "agent": { - "host": "localhost", - "http": { - "ipAddresses": ["127.0.0.1"], - "port": 8542 - } - } + zss: + enabled: true + tls: true + port: 8542 + crossMemoryServerName: ZWESIS_STD + # Only should be used with AT-TLS and is not secure + agent: + http: + ipAddresses: ["127.0.0.1"] ``` ### Connecting App Server to ZSS -When running the App Server, simply specify a few flags to declare which ZSS instance the App Server will proxy ZSS requests to: +When running the App Server script directly, simply specify a few flags to declare which ZSS instance the App Server will proxy ZSS requests to: - *-h*: Declares the host where ZSS can be found. Use as "-h \" - *-P*: Declares the port at which ZSS is listening. Use as "-P \" @@ -354,17 +355,26 @@ TTLSCipherParms cipher~ZSS ``` #### Configuring the Zowe App Server for HTTPS communication with ZSS -Copy the CA certificate to the ZSS server. Then in the Zowe App Server configuration file, specify the location of the certificate, and add a parameter to specify that ZSS uses AT-TLS. - -1. Enter the following command to copy the CA certificate to the correct location in UNIX System Services (USS): +Copy the CA certificate to the ZSS server. Then in the Zowe App Server configuration file, specify the location of the certificate, and add a parameter to specify that ZSS uses AT-TLS. Default signed certificates get generated during *zwe init* step in Zowe install. +1. Open the `zowe.yaml` file. +2. In the **zowe.certificates.pem** section, add the CA certificate file path in the *zowe.certificates.pem.certificateAuthorities* variable, for example: ``` -cp "//'[output_dataset_name]'" '[INSTANCE_DIR]/workspace/app-server/serverConfig/[ca_cert]' -``` -2. In the `[INSTANCE_DIR]/workspace/app-server/serverConfig` directory, open the `server.json` file. -3. In the **node.https.certificateAuthorities** object, add the CA certificate file path, for example: -``` -"certificateAuthorities": ["[INSTANCE_DIR]/workspace/app-server/serverConfig/[ca_cert]"] +# default certificate + certificate: + keystore: + type: PKCS12 + file: "/your-user/keystore-v2/localhost/localhost.keystore.p12" + password: "password" + alias: "localhost" + truststore: + type: PKCS12 + file: "/your-user/keystore-v2/localhost/localhost.truststore.p12" + password: "password" + pem: + key: "/your-user/keystore-v2/localhost/localhost.key" + certificate: "/your-user/keystore-v2/localhost/localhost.cer" + certificateAuthorities: "/your-user/keystore-v2/local_ca/local_ca.cer" ``` 4. In the **agent.http** object add the key-value pair `"attls": true`, for example: ``` @@ -392,7 +402,7 @@ The following steps assume you have installed a Zowe runtime instance (which inc 2. Create a new Zowe instance directory by following steps in [Creating and configuring the Zowe instance directory](configure-instance-directory.md). - **Note:** In the `instance.env` configuration file, specify ports that are not used by the first Zowe runtime. + **Note:** In the `zowe.yaml` configuration file, specify ports that are not used by the first Zowe runtime. 3. To restart the first Zowe runtime, in SDSF enter the following command: @@ -489,43 +499,40 @@ You control access by editing JSON files that list the apps. One file lists the You can also control access to the JSON files. The files are accessible directly on the file system, and since they are within the configuration dataservice directories, they are also accessible via REST API. We recommend that only Zowe administrators be allowed to access the file system locations, and you control that by setting the directories and their contents to have file permissions on z/OS that only allow the Zowe admin group read & write access. You control who can read and edit the JSON files through the REST API by controlling who can [access the configuration dataservice objects](mvd-configuration.md#creating-authorization-profiles) URLs that serve the JSON files. -### Controlling application access for all users +### Enabling RBAC -1. Open the Zowe Application Server configuration JSON file. By default, the file is in the following location: - ``` - $ROOT_DIR/components/app-server/share/zlux-app-server/defaults/serverConfig/server.json - ``` +By default, RBAC is disabled and all authenticated Zowe users can access all dataservices. To enable RBAC, follow these steps: + +1. To enable RBAC, set the `components.zss.dataserviceAuthentication.rbac` variable to `true` + +### Controlling application access for all users -2. To enable RBAC, in the `dataserviceAuthentication` object add the object: `"rbac": true` +1. Enable RBAC. -3. Navigate to the following location: +2. Navigate to the following location: ``` $ROOT_DIR/components/app-server/share/zlux-app-server/defaults/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins ``` -4. Copy the `allowedPlugins.json` file and paste it in the following location: +3. Copy the `allowedPlugins.json` file and paste it in the following location: ``` - .zowe/workspace/app-server/ZLUX/pluginStorage/org.zowe.zlux.bootstrap + $ROOT_DIR/components/app-server/share/zlux-app-server/deploy/instance/ZLUX/pluginStorage ``` -5. Open the copied `allowedPlugins.json` file and perform either of the following steps: +4. Open the copied `allowedPlugins.json` file and perform either of the following steps: - To an application unavailable, delete it from the list of objects. - To make an application available, copy an existing plugin object and specify the application's values in the new object. Identifier and version attributes are required. -6. [Restart the app server](configure-zowe-server.md#stopping-the-zwesvstc-proc). +5. [Restart the app server](configure-zowe-server.md#stopping-the-zwesvstc-proc). ### Controlling application access for individual users -1. Open the Zowe Application Server configuration JSON file. By default, the file is in the following location: - ``` - $ROOT_DIR/components/app-server/share/zlux-app-server/defaults/serverConfig/server.json - ``` -2. To enable RBAC, in the `dataserviceAuthentication` object add the object: `"rbac": true` +1. Enable RBAC. -3. In the user's ID directory path, in the `\pluginStorage` directory, create `\org.zowe.zlux.bootstrap\plugins` directories. For example: +2. In the user's ID directory path, in the `\pluginStorage` directory, create `\org.zowe.zlux.bootstrap\plugins` directories. For example: ``` - .zowe\workspace\app-server\users\TS6320\ZLUX\pluginStorage\org.zowe.zlux.bootstrap\plugins + $ROOT_DIR/components/app-server/share/zlux-app-server/deploy/instance/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins ``` -4. In the `/plugins` directory, create an `allowedPlugins.json` file. You can use the default `allowedPlugins.json` file as a template by copying it from the following location: +3. In the `/plugins` directory, create an `allowedPlugins.json` file. You can use the default `allowedPlugins.json` file as a template by copying it from the following location: ``` $ROOT_DIR/components/app-server/share/zlux-app-server/defaults/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins ``` @@ -589,14 +596,6 @@ If you use RACF security, take the following steps define the ZOWE class to the For more information RACF security administration, see the IBM Knowledge Center at [https://www.ibm.com/support/knowledgecenter/](https://www.ibm.com/support/knowledgecenter/). -### Enabling RBAC - -By default, RBAC is disabled and all authenticated Zowe users can access all dataservices. To enable RBAC, follow these steps: - -1. Open the Zowe Application Server configuration JSON file. In the a server instance, the configuration file is `$INSTANCE_DIR/workspace/app-server/serverConfig/server.json`. - -2. In the `dataserviceAuthentication` object, add `"rbac": true`. - ### Creating authorization profiles For users to access endpoints after you enable RBAC, in the ZOWE class you must create System Authorization Facility (SAF) profiles for each endpoint and give users READ access to those profiles. @@ -670,7 +669,7 @@ In the Desktop, Apps that you opened prior to expiration will remain open so tha ### Configuration -When you use the default Zowe SMP/E or convenience build configuration, you do not need to change Zowe to get started with MFA. +When you use the default Zowe SMP/E or convenience build configuration, you do not need to change Zowe to get started with MFA. To configure Zowe for MFA with a configuration other than the default, take the following steps: @@ -703,28 +702,33 @@ The following is an example configuration for `zss-auth`, as seen in a default i ## Enabling tracing -To obtain more information about how a server is working, you can enable tracing within the `server.json` file. +To obtain more information about how a server is working, you can enable tracing within the `zowe.yaml` file via *components.app-server.logLevels* variable. For example: ``` -"logLevels": { - "_zsf.routing": 0, - "_zsf.install": 0, - "_zss.traceLevel": 0, - "_zss.fileTrace": 1 -} +app-server: + {...} + logLevels: + _zsf.routing: 0 + _zsf.install: 0 ``` -Specify the following settings inside the **logLevels** object. +``` +zss: + {...} + logLevels: + _zss.traceLevel: 0 + _zss.fileTrace: 1 +``` All settings are optional. ### Zowe Application Server tracing -To determine how the Zowe Application Server (`zlux-app-server`) is working, you can assign a logging level to one or more of the pre-defined logger names in the `server.json` file. +To determine how the Zowe Application Server (`zlux-app-server`) is working, you can assign a logging level to one or more of the pre-defined logger names in the `zowe.yaml` file for the App server component (*components.app-server*). -The log prefix for the Zowe Application Server is **_zsf**, which is used by the server framework. (Applications and plug-ins that are attached to the server do not use the **_zsf** prefix.) +The log prefix for the Zowe Application Server is **_zsf**, which is used by the server framework. (Applications and plugins that are attached to the server do not use the **_zsf** prefix.) The following are the logger names that you can specify: @@ -747,13 +751,13 @@ Logging for miscellaneous utilities that the server relies upon. Logging for proxies that are set up in the server. **_zsf.install** -Logging for the installation of plug-ins. +Logging for the installation of plugins. **_zsf.apiml** Logging for communication with the api mediation layer. **_zsf.routing** -Logging for dispatching network requests to plug-in dataservices. +Logging for dispatching network requests to plugin dataservices. **_zsf.network** Logging for the HTTPS server status (connection, ports, IP, and so on) @@ -773,7 +777,7 @@ FINE, FINER, and FINEST are log levels for debugging, with increasing verbosity. ### Enabling tracing for ZSS -To increase logging for ZSS, you can assign a logging level (an integer value greater than zero) to one or more of the pre-defined logger names in the `server.json` file. +To increase logging for ZSS, you can assign a logging level (an integer value greater than zero) to one or more of the pre-defined logger names in the `zowe.yaml` file for the ZSS component (*components.zss*). A higher value specifies greater verbosity. @@ -811,17 +815,17 @@ When you are finished specifying the settings, save the `server.json` file. ## Zowe Application Framework logging -The Zowe Application Framework log files contain processing messages and statistics. The log files are generated in the following default locations: +The Zowe Application Framework log files contain processing messages and statistics. The log files are generated the specified log location (*zowe.logDirectory*) in the `zowe.yaml` file: -- Zowe Application Server: `$INSTANCE_DIR/logs/appServer-yyyy-mm-dd-hh-mm.log` -- ZSS: `$INSTANCE_DIR/logs/zssServer-yyyy-mm-dd-hh-mm.log` +- Zowe Application Server: `{your-location}/appServer-yyyy-mm-dd-hh-mm.log` +- ZSS: `{your-location}/zssServer-yyyy-mm-dd-hh-mm.log` -The logs are timestamped in the format yyyy-mm-dd-hh-mm and older logs are deleted when a new log is created at server startup. +The logs are timestamped in the format yyyy-mm-dd-hh-mm and older logs (by default, last five are retained) are deleted when a new log is created at server startup. ### Controlling the logging location -The log information is written to a file and to the screen. (On Windows, logs are written to a file only.) +The log information is written to a file and to the screen. (On Windows, logs are written to a screen only.) #### ZLUX_NODE_LOG_DIR and ZSS_LOG_DIR environment variables From 583af80fde0598dd6722a73ce266d8894fbbd04b Mon Sep 17 00:00:00 2001 From: Leanid Astrakou Date: Fri, 4 Mar 2022 17:28:52 -0500 Subject: [PATCH 02/17] Updated Configuring App server for HTTPS + typo Signed-off-by: Leanid Astrakou --- docs/user-guide/mvd-configuration.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index b8a4faedcb..71682aab36 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -17,7 +17,7 @@ For earlier releases, you must register the Application Server with the Mediatio ### Accessing the Application Server -**Note:** Before Accessing the Application Server, first [first install and configure the Zowe instance](configure-instance-directory.md). +**Note:** Before Accessing the Application Server, first [install and configure the Zowe instance](configure-instance-directory.md). To access the Application Server through the Mediation Layer, use the Mediation Layer gateway server hostname and port. For example, when accessed directly, this is Zowe Desktop URL: `https:///ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` @@ -376,16 +376,17 @@ Copy the CA certificate to the ZSS server. Then in the Zowe App Server configura certificate: "/your-user/keystore-v2/localhost/localhost.cer" certificateAuthorities: "/your-user/keystore-v2/local_ca/local_ca.cer" ``` -4. In the **agent.http** object add the key-value pair `"attls": true`, for example: +3. In the **components.zss.agent.http** section add the key-value pair `attls: true`, for example: ``` -"agent": { - "host": "localhost", - "http": { - "ipAddresses": ["127.0.0.1"], - "port": 8542, - "attls": true - } -} +zss: + enabled: true + port: 8542 + crossMemoryServerName: ZWESIS_STD + tls: true + agent: + http: + ipAddresses: ["127.0.0.1"] + attls: true ``` ### Installing additional ZSS instances From 3272e32c446a01721f288c3a9a440f3f6703e619 Mon Sep 17 00:00:00 2001 From: Leanid Astrakou Date: Fri, 4 Mar 2022 17:36:21 -0500 Subject: [PATCH 03/17] Typo Signed-off-by: Leanid Astrakou --- docs/user-guide/mvd-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 71682aab36..2d38ae384e 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -64,7 +64,7 @@ ZSS reads this file directly as a startup argument, while the Zowe Application S ## Environment variables -In Zowe V1, environment variables were originally specified in `instance.env`. In V2, while most variables can be customized in corresponding component sections of `zowe.yaml`, additional enviornment variables can be specified in `zowe.environments` section. +In Zowe V1, environment variables were originally specified in `instance.env`. In V2, while most variables can be customized in corresponding component sections of `zowe.yaml`, additional environment variables can be specified in `zowe.environments` section. ## Network configuration From 57bc4479cd4747a6e6971d6e26e186addbe6c4d5 Mon Sep 17 00:00:00 2001 From: Leanid Astrakou Date: Fri, 4 Mar 2022 17:38:15 -0500 Subject: [PATCH 04/17] Small reword Signed-off-by: Leanid Astrakou --- docs/user-guide/mvd-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 2d38ae384e..3907d3f616 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -140,7 +140,7 @@ These directories dictate where the [Configuration Dataservice](https://github.c ``` ### Old defaults -Prior to Zowe release 2.0.0, the location of the configuration directories were initialized to be within the `` folder unless otherwise customized. 2.0.0 does have backwards compatibility for the existence of these directories, but `` folder no longer exists, so they should be migrated to new locations. +Prior to Zowe release 2.0.0, the location of the configuration directories were initialized to be within the `` folder unless otherwise customized. 2.0.0 does have backwards compatibility for the existence of these directories, but `` folder no longer exists, so they should be migrated to match the ones specified in `zowe.yaml`. | Folder | New Location | Old Location | Note |--------|--------------|--------------|----- From 01935a7e7bccdf5aeb010ee1a64bd9540f8c3801 Mon Sep 17 00:00:00 2001 From: Leanid Astrakou Date: Fri, 4 Mar 2022 17:40:08 -0500 Subject: [PATCH 05/17] Better extensionsDir example Signed-off-by: Leanid Astrakou --- docs/user-guide/mvd-configuration.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 3907d3f616..0602c7af55 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -162,8 +162,9 @@ To include application plugins, define the location of the plugins directory in ### Plugins directory example ``` -// All paths should be absolute -//... +zowe + {...} + # All paths should be absolute # Where extensions are installed extensionDirectory: /your-user/zowe/extensions ``` From 2e3f0048e16523f1c2d4746b19c7f3b3937e2d98 Mon Sep 17 00:00:00 2001 From: Leanid Astrakou Date: Fri, 4 Mar 2022 17:41:23 -0500 Subject: [PATCH 06/17] Added word Signed-off-by: Leanid Astrakou --- docs/user-guide/mvd-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 0602c7af55..73b807590f 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -356,7 +356,7 @@ TTLSCipherParms cipher~ZSS ``` #### Configuring the Zowe App Server for HTTPS communication with ZSS -Copy the CA certificate to the ZSS server. Then in the Zowe App Server configuration file, specify the location of the certificate, and add a parameter to specify that ZSS uses AT-TLS. Default signed certificates get generated during *zwe init* step in Zowe install. +Copy the CA certificate to the ZSS server. Then in the Zowe App Server configuration file, specify the location of the certificate, and add a parameter to specify that ZSS uses AT-TLS. Default self signed certificates get generated during *zwe init* step in Zowe install. 1. Open the `zowe.yaml` file. 2. In the **zowe.certificates.pem** section, add the CA certificate file path in the *zowe.certificates.pem.certificateAuthorities* variable, for example: From ca523801f00dde9011a590cde8d0760ed99f5f28 Mon Sep 17 00:00:00 2001 From: Leanid Astrakou Date: Tue, 8 Mar 2022 21:19:07 -0500 Subject: [PATCH 07/17] Curses! Signed-off-by: Leanid Astrakou --- docs/user-guide/mvd-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 73b807590f..6ce4283e4c 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -383,7 +383,7 @@ zss: enabled: true port: 8542 crossMemoryServerName: ZWESIS_STD - tls: true + tls: false agent: http: ipAddresses: ["127.0.0.1"] From 41fc97905e9372640bdd6f7834bba91a111976e2 Mon Sep 17 00:00:00 2001 From: Leanid Astrakou Date: Tue, 8 Mar 2022 21:23:35 -0500 Subject: [PATCH 08/17] TODO comment Signed-off-by: Leanid Astrakou --- docs/user-guide/mvd-configuration.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 6ce4283e4c..21754b282f 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -142,6 +142,14 @@ These directories dictate where the [Configuration Dataservice](https://github.c ### Old defaults Prior to Zowe release 2.0.0, the location of the configuration directories were initialized to be within the `` folder unless otherwise customized. 2.0.0 does have backwards compatibility for the existence of these directories, but `` folder no longer exists, so they should be migrated to match the ones specified in `zowe.yaml`. + + + +TODO: New location values are all wrong + + + + | Folder | New Location | Old Location | Note |--------|--------------|--------------|----- | siteDir | zlux-app-server/deploy/site | /workspace/app-server/site | From b2e12a5e4be77259078fa2ca5229449c40201a89 Mon Sep 17 00:00:00 2001 From: Leanid Astrakou Date: Mon, 14 Mar 2022 13:12:06 -0400 Subject: [PATCH 09/17] AT-TLS doc update Signed-off-by: Leanid Astrakou --- docs/user-guide/mvd-configuration.md | 51 +++++++--------------------- 1 file changed, 13 insertions(+), 38 deletions(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 21754b282f..8a8dacd743 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -185,7 +185,7 @@ For more information, see [Logging Utility](../extend/extend-desktop/mvd-logutil Running ZSS requires a `zowe.yaml` configuration that is similar to the one used for the Zowe Application Server. The attributes that are needed for ZSS (*components.zss*) at minimum, are: *port*, *crossMemoryServerName*. -For example, *port* is the TCP port that ZSS will listen on to be contacted by the App Server. Define this in the configuration file as a value between 1024-65535. Similarly, if specified, *agent.http.ipAddresses* will be used to determine which IP addresses the server should bind to (note: Should only be used with AT-TLS and is not secure, otherwise use HTTPS). Only the first value of the array is used. It can either be a hostname or an IPv4 address. +For example, *port* is the TCP port that ZSS will listen on to be contacted by the App Server. Define this in the configuration file as a value between 1024-65535. ZSS is HTTPS by default, so AT-TLS is optional and if you were to enable AT-TLS, you need to disable HTTPS. Similarly, if specified, *agent.http.ipAddresses* will be used to determine which IP addresses the server should bind to (note: Should only be used with AT-TLS and is not secure, otherwise use HTTPS). Only the first value of the array is used. It can either be a hostname or an IPv4 address. Example of the agent body: ``` @@ -208,13 +208,16 @@ When running the App Server script directly, simply specify a few flags to decla - *-P*: Declares the port at which ZSS is listening. Use as "-P \" ### Configuring ZSS for HTTPS -To secure ZSS communication, you can use Application Transparent Transport Layer Security (AT-TLS) to enable Hyper Text Transfer Protocol Secure (HTTPS) communication with ZSS. -Before you begin, you must have a basic knowledge of your security product, e.g. RACF, and AT-TLS, and you must have Policy Agent configured. For more information on [AT-TLS](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.halx001/transtls.htm) and [Policy Agent](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2.halz002/pbn_pol_agnt.htm), see the [z/OS Knowledge Center](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2/en/homepage.html). +By default, ZSS is enabled in HTTPS and doesn't require an advanced configuration. + +If you want to use RACF or AT-TLS (which requires ZSS to be in HTTP mode), you must have a basic knowledge of your security product and you must have Policy Agent configured. For more information on [AT-TLS](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.halx001/transtls.htm) and [Policy Agent](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2.halz002/pbn_pol_agnt.htm), see the [z/OS Knowledge Center](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2/en/homepage.html). You must have the authority to alter security definitions related to certificate management, and you must be authorized to work with and update the Policy Agent. -To configure HTTPS communication between ZSS and the Zowe App Server, you need a key ring which contains the ZSS server certificate and its Certificate Authority (CA) certificate. You can use an internal CA to create the ZSS server certificate, or you can buy the ZSS server certificate from a well-known commercial Certificate Authority. Next you define an AT-TLS rule which points to the key ring used by the ZSS server. Then you copy the CA certificate to the Zowe App Server key store and update the Zowe App Server configuration file. +By default, HTTPS communication between ZSS and App Server is done via a server certificate, its Certificate Authority (CA) certificate, and keystore generated during the Zowe initialization step (`zwe init`). + +You may also use a key ring which contains the ZSS server certificate and its Certificate Authority certificate. You can use an internal CA to create the ZSS server certificate, or you can buy the ZSS server certificate from a well-known commercial Certificate Authority. Next you define an AT-TLS rule which points to the key ring used by the ZSS server. Then you copy the CA certificate to the Zowe App Server key store and update the Zowe App Server configuration file. **Note:** Bracketed values below (including the brackets) are variables. Replace them with values relevant to your organization. Always use the same value when substituting a variable that occurs multiple times. @@ -364,10 +367,10 @@ TTLSCipherParms cipher~ZSS ``` #### Configuring the Zowe App Server for HTTPS communication with ZSS -Copy the CA certificate to the ZSS server. Then in the Zowe App Server configuration file, specify the location of the certificate, and add a parameter to specify that ZSS uses AT-TLS. Default self signed certificates get generated during *zwe init* step in Zowe install. +In the `zowe.yaml` configuration file, specify the location of the certificate. Default self signed certificates get generated during `zwe init` step in the Zowe install. 1. Open the `zowe.yaml` file. -2. In the **zowe.certificates.pem** section, add the CA certificate file path in the *zowe.certificates.pem.certificateAuthorities* variable, for example: +2. In the **zowe.certificates.pem** section, add the certificate file path, type, and other variables as needed in the *zowe.certificates* variable, for example: ``` # default certificate certificate: @@ -385,7 +388,7 @@ Copy the CA certificate to the ZSS server. Then in the Zowe App Server configura certificate: "/your-user/keystore-v2/localhost/localhost.cer" certificateAuthorities: "/your-user/keystore-v2/local_ca/local_ca.cer" ``` -3. In the **components.zss.agent.http** section add the key-value pair `attls: true`, for example: +3. (optional - AT-TLS with HTTP) In the **components.zss.agent.http** section add the key-value pair `attls: true` with *ipAddresses* variable, for example: ``` zss: enabled: true @@ -472,34 +475,6 @@ The following steps assume you have installed a Zowe runtime instance (which inc `ZIS status - Ok (name='ZWESIS_MYSRV ', cmsRC=0, description='Ok', clientVersion=2)` -### Configuring AT-TLS on Client System - -When connecting to a Zowe instance whose host system is configured to use AT-TLS for HTTPS, the connecting client/client system must also define an outbound AT-TLS rule. To define the AT-TLS rule, use the sample below to specify values in your AT-TLS Policy Agent Configuration file: - -``` -TTLSRule XYZClientRule -{ - RemotePortRange [gateway_or_desktop_port] - Direction Outbound - TTLSGroupActionRef XYZGroup - TTLSEnvironmentActionRef XYZClientEnvironment -} -TTLSGroupAction XYZGroup -{ - TTLSEnabled On -} -TTLSEnvironmentAction XYZClientEnvironment -{ - TTLSKeyRingParms - { - Keyring [client_key_ring] - } - HandshakeRole CLIENT - Trace 7 -} -``` - -**Note:** \[client_key_ring\] is a key ring containing the client certificate. To retrieve a signed client certificate, contact the administrator of the host system. ## Controlling access to applications @@ -513,7 +488,7 @@ You can also control access to the JSON files. The files are accessible directly By default, RBAC is disabled and all authenticated Zowe users can access all dataservices. To enable RBAC, follow these steps: -1. To enable RBAC, set the `components.zss.dataserviceAuthentication.rbac` variable to `true` +1. To enable RBAC, set the *components.zss.dataserviceAuthentication.rbac* variable to `true` ### Controlling application access for all users @@ -553,7 +528,7 @@ By default, RBAC is disabled and all authenticated Zowe users can access all dat { "identifier": "org.zowe.appA", "versions": [ - "*" + "1.1" ] }, { @@ -604,7 +579,7 @@ If you use RACF security, take the following steps define the ZOWE class to the SETROPTS CLASSACT(ZOWE) ``` -For more information RACF security administration, see the IBM Knowledge Center at [https://www.ibm.com/support/knowledgecenter/](https://www.ibm.com/support/knowledgecenter/). +For more information on RACF security administration, see the IBM Knowledge Center at [https://www.ibm.com/support/knowledgecenter/](https://www.ibm.com/support/knowledgecenter/). ### Creating authorization profiles For users to access endpoints after you enable RBAC, in the ZOWE class you must create System Authorization Facility (SAF) profiles for each endpoint and give users READ access to those profiles. From 4633442063d9f0a5aa9fed4e28379679c0639410 Mon Sep 17 00:00:00 2001 From: Leanid Astrakou Date: Mon, 14 Mar 2022 22:02:52 -0400 Subject: [PATCH 10/17] AT-TLS touch-up Signed-off-by: Leanid Astrakou --- docs/user-guide/mvd-configuration.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 8a8dacd743..e582e21840 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -185,7 +185,7 @@ For more information, see [Logging Utility](../extend/extend-desktop/mvd-logutil Running ZSS requires a `zowe.yaml` configuration that is similar to the one used for the Zowe Application Server. The attributes that are needed for ZSS (*components.zss*) at minimum, are: *port*, *crossMemoryServerName*. -For example, *port* is the TCP port that ZSS will listen on to be contacted by the App Server. Define this in the configuration file as a value between 1024-65535. ZSS is HTTPS by default, so AT-TLS is optional and if you were to enable AT-TLS, you need to disable HTTPS. Similarly, if specified, *agent.http.ipAddresses* will be used to determine which IP addresses the server should bind to (note: Should only be used with AT-TLS and is not secure, otherwise use HTTPS). Only the first value of the array is used. It can either be a hostname or an IPv4 address. +For example, *port* is the TCP port that ZSS will listen on to be contacted by the App Server. Define this in the configuration file as a value between 1024-65535. ZSS is HTTPS by default, so AT-TLS is optional and if you were to enable AT-TLS, you need to disable HTTPS. Similarly, if specified, *agent.http.ipAddresses* will be used to determine which IP addresses the server should bind to (note: Should only be used with AT-TLS and is not secure). Only the first value of the array is used. It can either be a hostname or an IPv4 address. Example of the agent body: ``` @@ -194,10 +194,11 @@ Example of the agent body: tls: true port: 8542 crossMemoryServerName: ZWESIS_STD - # Only should be used with AT-TLS and is not secure + # The following is not secure & should only be used with AT-TLS and tls: false agent: http: ipAddresses: ["127.0.0.1"] + attls: true ``` ### Connecting App Server to ZSS @@ -388,7 +389,10 @@ In the `zowe.yaml` configuration file, specify the location of the certificate. certificate: "/your-user/keystore-v2/localhost/localhost.cer" certificateAuthorities: "/your-user/keystore-v2/local_ca/local_ca.cer" ``` -3. (optional - AT-TLS with HTTP) In the **components.zss.agent.http** section add the key-value pair `attls: true` with *ipAddresses* variable, for example: + +Note: .pem files have no encryption in them so they are a security concern. Zowe by default should use .p12 files. + +3. (optional - not secure) In the **components.zss.agent.http** section add the key-value pair `attls: true` with *ipAddresses* variable to enable AT-TLS, for example: ``` zss: enabled: true From 00eaea59b43d4136cb31cd1976fda4bccb46f2ea Mon Sep 17 00:00:00 2001 From: Leanid Astrakou Date: Tue, 15 Mar 2022 09:30:02 -0400 Subject: [PATCH 11/17] Update Desktop URLs for V2 Signed-off-by: Leanid Astrakou --- docs/user-guide/mvd-configuration.md | 32 +++++++++++++++++----------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index e582e21840..ade92387ba 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -1,32 +1,38 @@ # Configuring Zowe Application Framework -After you install Zowe™, you can optionally configure the Zowe Application Framework as a Mediation Layer client, configure connections for the terminal application plugins, or modify the Zowe Application Server and Zowe System Services (ZSS) configuration, as needed. +After you install Zowe™, the Zowe Application Framework is configured as a Mediation Layer client by default. This is simpler to administer because the framework servers are accessible externally through a single port: API ML Gateway port. It is more secure because you can implement stricter browser security policies for accessing cross-origin content. -## Configuring the framework as a Mediation Layer client -For simpler Zowe administration and better security, you can install an instance of the Zowe Application Framework as an API Mediation Layer client. - -This configuration is simpler to administer because the framework servers are accessible externally through a single port: API ML Gateway port. It is more secure because you can implement stricter browser security policies for accessing cross-origin content. - -You must use SSL certificates to configure the Zowe Application Server to communicate with the SSL-enabled Mediation Layer. Those certificates were created during the Zowe installation process, and are located in the `$RUNTIME_DIR/components/app-server/share/zlux-app-server/defaults/serverConfig` directory. +You can modify the Zowe Application Server and Zowe System Services (ZSS) configuration, as needed, or configure connections for the Terminal application plugins. -### Enabling the Application Server to register with the Mediation Layer +## Configuring the framework as a Mediation Layer client When you install Zowe v1.8.0 or later, the Application Server automatically registers with the Mediation Layer. For earlier releases, you must register the Application Server with the Mediation Layer manually. Refer to previous release documentation for more information. +You must use SSL certificates for the Zowe Application Server to communicate with the SSL-enabled Mediation Layer. These certificates are created, and used by default, during the Zowe installation process (`zwe init` step) and are located in *zowe.certificate* section in `zowe.yaml`. + ### Accessing the Application Server + +TODO: Should configure-instance-directory renamed to configure Zowe runtime directory? + + **Note:** Before Accessing the Application Server, first [install and configure the Zowe instance](configure-instance-directory.md). -To access the Application Server through the Mediation Layer, use the Mediation Layer gateway server hostname and port. For example, when accessed directly, this is Zowe Desktop URL: `https:///ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` +Recommended: To access the Application Server (Zowe Desktop) through the Mediation Layer, use the Mediation Layer gateway server hostname and port. + +`https://:/zlux/ui/v1/` or +`https://:/zlux/ui/v1/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` + +To access the Application Server directly, use the App server hostname and port. -The port number for the Zowe Desktop is the value of the `components.app-server.port` variable in the `zowe.yaml` file in the instance directory, see [Creating and configuring the Zowe instance directory](configure-instance-directory.md). +`https://:` or +`https://:/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` -When accessed through the API Mediation Layer, this is the Zowe Desktop URL: -`https:///zlux/ui/v1/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` +The port number for the Zowe Desktop is the value of the *components.app-server.port* variable in `zowe.yaml`, see [Creating and configuring the Zowe instance directory](configure-instance-directory.md). -The port number for the API Mediation Layer is the value of the `components.gateway.port` variable in the `zowe.yaml` file in the instance directory. +The port number for the API Mediation Layer is the value of the *components.gateway.port* variable in `zowe.yaml`. ## Setting up terminal application plugins From fe88c2d5568646d2d8317a3f890a7064b6f40f5b Mon Sep 17 00:00:00 2001 From: Leanid Astrakou Date: Tue, 15 Mar 2022 09:55:05 -0400 Subject: [PATCH 12/17] Minor touch-up for Desktop URL + SSL sentences Signed-off-by: Leanid Astrakou --- docs/user-guide/mvd-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index ade92387ba..7f4ae7b406 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -10,7 +10,7 @@ When you install Zowe v1.8.0 or later, the Application Server automatically regi For earlier releases, you must register the Application Server with the Mediation Layer manually. Refer to previous release documentation for more information. -You must use SSL certificates for the Zowe Application Server to communicate with the SSL-enabled Mediation Layer. These certificates are created, and used by default, during the Zowe installation process (`zwe init` step) and are located in *zowe.certificate* section in `zowe.yaml`. +You must use SSL certificates for the Zowe Application Server to communicate with the SSL-enabled Mediation Layer. These certificates are designated by *zowe.certificate* section in `zowe.yaml` and are created, by default, during the Zowe installation process (`zwe init` step). ### Accessing the Application Server @@ -25,7 +25,7 @@ Recommended: To access the Application Server (Zowe Desktop) through the Mediati `https://:/zlux/ui/v1/` or `https://:/zlux/ui/v1/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` -To access the Application Server directly, use the App server hostname and port. +(Not recommended): To access the Application Server directly, use the App server hostname and port. `https://:` or `https://:/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` From dfc28c7e409722262d52f1fb7c6b188af10ddc9b Mon Sep 17 00:00:00 2001 From: Leanid Astrakou Date: Tue, 22 Mar 2022 10:51:48 -0400 Subject: [PATCH 13/17] Code review changes Signed-off-by: Leanid Astrakou --- docs/user-guide/mvd-configuration.md | 335 ++++++++------------------- 1 file changed, 99 insertions(+), 236 deletions(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 7f4ae7b406..d15858feff 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -1,44 +1,47 @@ # Configuring Zowe Application Framework -After you install Zowe™, the Zowe Application Framework is configured as a Mediation Layer client by default. This is simpler to administer because the framework servers are accessible externally through a single port: API ML Gateway port. It is more secure because you can implement stricter browser security policies for accessing cross-origin content. +The Zowe Application ("App") Framework is configured in the Zowe configuration file. Configuration can be used to change things such as verbosity of logs, the way in which the App server communicates with the Mediation Layer, how ZSS operates, whether to use HTTPS or AT-TLS, what language the logs should be set, and many more attributes. -You can modify the Zowe Application Server and Zowe System Services (ZSS) configuration, as needed, or configure connections for the Terminal application plugins. +When you install Zowe™, the App Framework is configured as a Mediation Layer client by default. This is simpler to administer because the App framework servers are accessible externally through a single port: API ML Gateway port. It is more secure because you can implement stricter browser security policies for accessing cross-origin content. -## Configuring the framework as a Mediation Layer client - -When you install Zowe v1.8.0 or later, the Application Server automatically registers with the Mediation Layer. - -For earlier releases, you must register the Application Server with the Mediation Layer manually. Refer to previous release documentation for more information. +You can modify the Zowe App Server and Zowe System Services (ZSS) configuration, as needed, or configure connections for the Terminal app plugins. -You must use SSL certificates for the Zowe Application Server to communicate with the SSL-enabled Mediation Layer. These certificates are designated by *zowe.certificate* section in `zowe.yaml` and are created, by default, during the Zowe installation process (`zwe init` step). +## Configuring the framework as a Mediation Layer client -### Accessing the Application Server +When you install Zowe v1.8.0 or later, the App Server automatically registers with the Mediation Layer. +For earlier releases, you must register the App Server with the Mediation Layer manually. Refer to previous release documentation for more information. -TODO: Should configure-instance-directory renamed to configure Zowe runtime directory? +The App server utilizes the certificates set up for use by all of Zowe as specified in the Zowe configuration file. See [Zowe certificate configuration section](../user-guide/configure-certificates.md#configuring-zowe-certificates) for more information. +### Accessing the App Server -**Note:** Before Accessing the Application Server, first [install and configure the Zowe instance](configure-instance-directory.md). +When the server is enabled in the configuration file, the App server is accessible via the following URL. ZWED0031I message code can tell us when the App server is ready to be accessed. -Recommended: To access the Application Server (Zowe Desktop) through the Mediation Layer, use the Mediation Layer gateway server hostname and port. +Recommended: To access the App Server (Zowe Desktop) through the Mediation Layer, use the Mediation Layer gateway server hostname and port. `https://:/zlux/ui/v1/` or `https://:/zlux/ui/v1/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` -(Not recommended): To access the Application Server directly, use the App server hostname and port. +(Not recommended): To access the App Server directly, use the App server hostname and port. `https://:` or `https://:/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` -The port number for the Zowe Desktop is the value of the *components.app-server.port* variable in `zowe.yaml`, see [Creating and configuring the Zowe instance directory](configure-instance-directory.md). +You should be accessing the App server via the Gateway port, but the App server still needs a port assigned to it which is the value of the *components.app-server.port* variable in the Zowe configuration file, see [Creating and configuring the Zowe instance directory](configure-instance-directory.md). + -The port number for the API Mediation Layer is the value of the *components.gateway.port* variable in `zowe.yaml`. +TODO: Above linked file needs to be changed -## Setting up terminal application plugins -Follow these optional steps to configure the default connection to open for the terminal application plugins. -### Setting up the TN3270 mainframe terminal application plugin +The port number for the API Mediation Layer is the value of the *components.gateway.port* variable in the same file. + +## Setting up terminal app plugins + +Follow these optional steps to configure the default connection to open for the terminal app plugins. + +### Setting up the TN3270 mainframe terminal app plugin `_defaultTN3270.json` is a file in `tn3270-ng2/`, which is deployed during setup. Within this file, you can specify the following parameters to configure the terminal connection: ``` @@ -48,7 +51,7 @@ Follow these optional steps to configure the default connection to open for the type: <"telnet" or "tls"> } ``` -### Setting up the VT Terminal application plugin +### Setting up the VT Terminal app plugin `_defaultVT.json` is a file in `vt-ng2/`, which is deployed during setup. Within this file, you can specify the following parameters to configure the terminal connection: ``` @@ -61,22 +64,24 @@ Follow these optional steps to configure the default connection to open for the ## Configuration file -The Zowe App Server and ZSS rely on many required or optional parameters to run, which includes setting up networking, deployment directories, plugin locations, and more. - -For convenience, the Zowe Application Server and ZSS read from the `zowe.yaml` file with a common structure, i.e. `components.app-server` and `components.zss`. -ZSS reads this file directly as a startup argument, while the Zowe Application Server (as defined in the `zlux-server-framework` repository) accepts several parameters. The parameters are intended to be read from a JSON file through an implementer of the server, such as the example in the `zlux-app-server` repository (the `lib/zluxServer.js` file). The file accepts a JSON file that specifies most, if not all, of the parameters needed. Other parameters can be provided through flags, if needed. - -**Note:** All examples are based on the *zlux-app-server* repository defaults. +For convenience, the App Server and ZSS share nearly identical configurations and read from the Zowe configuration file (via `components.app-server` and `components.zss`). Some values of configuration can be specified in the App server or ZSS sections. It is possible for each of these servers to read each others' sections to learn about their configuration. ## Environment variables -In Zowe V1, environment variables were originally specified in `instance.env`. In V2, while most variables can be customized in corresponding component sections of `zowe.yaml`, additional environment variables can be specified in `zowe.environments` section. +In Zowe V1, environment variables were originally specified in `instance.env`. In V2, while most variables can be customized in corresponding component sections of the Zowe configuration file, additional environment variables can be specified in `zowe.environments` section. ## Network configuration -**Note:** The following attributes are to be defined in the `zowe.yaml` file. +**Note:** The following attributes are to be defined in the Zowe configuration file. + +The App Server can be accessed over HTTP and/or HTTPS, provided it has been configured for either. HTTPS should be used, as HTTP is not secure unless AT-TLS is used. `components.zss.tls` variable must be set to false in Zowe configuration file to use HTTP and AT-TLS. + + + +TODO: Trim this section below + + -The App Server can be accessed over HTTP and/or HTTPS, provided it has been configured for either. ### HTTP @@ -146,42 +151,20 @@ These directories dictate where the [Configuration Dataservice](https://github.c ``` ### Old defaults -Prior to Zowe release 2.0.0, the location of the configuration directories were initialized to be within the `` folder unless otherwise customized. 2.0.0 does have backwards compatibility for the existence of these directories, but `` folder no longer exists, so they should be migrated to match the ones specified in `zowe.yaml`. - - - - -TODO: New location values are all wrong - - - +Prior to Zowe release 2.0.0, the location of the configuration directories were initialized to be within the `` folder unless otherwise customized. 2.0.0 does have backwards compatibility for the existence of these directories, but `` folder no longer exists, so they should be migrated to match the ones specified in the Zowe configuration file. | Folder | New Location | Old Location | Note |--------|--------------|--------------|----- -| siteDir | zlux-app-server/deploy/site | /workspace/app-server/site | -| instanceDir | zlux-app-server/deploy/instance | /workspace/app-server | -| groupsDir | zlux-app-server/deploy/instance/groups | /workspace/app-server/groups | -| usersDir | zlux-app-server/deploy/instance/users | /workspace/app-server/users | -| pluginsDir | zlux-app-server/deploy/instance/ZLUX/plugins | /workspace/app-server/plugins | Defaults located at zlux-app-server/defaults/plugins - - -## Application plugin configuration +| siteDir | /app-server/site | /workspace/app-server/site | +| instanceDir | /app-server | /workspace/app-server | instanceDir term isn't used anymore. workspaceDirectory is used +| groupsDir | /app-server/groups | /workspace/app-server/groups | +| usersDir | /app-server/users | /workspace/app-server/users | +| pluginsDir | /app-server/plugins | /workspace/app-server/plugins | -This topic describes application plugins that are defined in advance. -In the configuration file, you can specify a directory that contains JSON files, which tell the server what application plugin to include and where to find it on disk. The backend of these application plugins use the server's plugin structure, therefore much of the server-side references to application plugins use the term *plugin*. +## App plugin configuration -To include application plugins, define the location of the plugins directory in the `zowe.yaml` file, via *zowe.extensionDirectory* variable. - -### Plugins directory example - -``` -zowe - {...} - # All paths should be absolute - # Where extensions are installed - extensionDirectory: /your-user/zowe/extensions -``` +The App server will load plugins from extensions and components based upon their enabled status in Zowe configuration. The server caches knowledge of these plugins in the `/app-server/plugins` folder. This location can be customized with the *components.app-server.pluginsDir* variable in the Zowe configuration file. ## Logging configuration @@ -189,42 +172,41 @@ For more information, see [Logging Utility](../extend/extend-desktop/mvd-logutil ## ZSS configuration -Running ZSS requires a `zowe.yaml` configuration that is similar to the one used for the Zowe Application Server. The attributes that are needed for ZSS (*components.zss*) at minimum, are: *port*, *crossMemoryServerName*. +Running ZSS requires a Zowe configuration file configuration that is similar to the one used for the Zowe App Server (by structure and property names). The attributes that are needed for ZSS (*components.zss*) at minimum, are: *port*, *crossMemoryServerName*. -For example, *port* is the TCP port that ZSS will listen on to be contacted by the App Server. Define this in the configuration file as a value between 1024-65535. ZSS is HTTPS by default, so AT-TLS is optional and if you were to enable AT-TLS, you need to disable HTTPS. Similarly, if specified, *agent.http.ipAddresses* will be used to determine which IP addresses the server should bind to (note: Should only be used with AT-TLS and is not secure). Only the first value of the array is used. It can either be a hostname or an IPv4 address. +By default, ZSS is configured to use HTTPS with the same certificate information and port specification as the other Zowe services. If you are looking to use AT-TLS instead, then you must set *component.zss.tls* variable to false and define `component.zss.agent.http` section with port, ipAddresses, and attls: true as shown below -Example of the agent body: +(Recommended) Example of the agent body: ``` - zss: - enabled: true - tls: true - port: 8542 - crossMemoryServerName: ZWESIS_STD - # The following is not secure & should only be used with AT-TLS and tls: false - agent: - http: - ipAddresses: ["127.0.0.1"] - attls: true +zss: + enabled: true + tls: true + port: 8542 + crossMemoryServerName: ZWESIS_STD ``` -### Connecting App Server to ZSS - -When running the App Server script directly, simply specify a few flags to declare which ZSS instance the App Server will proxy ZSS requests to: - -- *-h*: Declares the host where ZSS can be found. Use as "-h \" -- *-P*: Declares the port at which ZSS is listening. Use as "-P \" +(Not recommended) Unsecure, HTTP example with AT-TLS: +``` +zss: + enabled: true + port: 8542 + crossMemoryServerName: ZWESIS_STD + tls: false + agent: + http: + ipAddresses: ["127.0.0.1"] + attls: true +``` -### Configuring ZSS for HTTPS +### Configuring ZSS for AT-TLS -By default, ZSS is enabled in HTTPS and doesn't require an advanced configuration. +By default, ZSS is enabled in HTTPS and doesn't require an advanced configuration outside the required attributes in the recommended example above. If you want to use RACF or AT-TLS (which requires ZSS to be in HTTP mode), you must have a basic knowledge of your security product and you must have Policy Agent configured. For more information on [AT-TLS](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.halx001/transtls.htm) and [Policy Agent](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2.halz002/pbn_pol_agnt.htm), see the [z/OS Knowledge Center](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2/en/homepage.html). You must have the authority to alter security definitions related to certificate management, and you must be authorized to work with and update the Policy Agent. -By default, HTTPS communication between ZSS and App Server is done via a server certificate, its Certificate Authority (CA) certificate, and keystore generated during the Zowe initialization step (`zwe init`). - -You may also use a key ring which contains the ZSS server certificate and its Certificate Authority certificate. You can use an internal CA to create the ZSS server certificate, or you can buy the ZSS server certificate from a well-known commercial Certificate Authority. Next you define an AT-TLS rule which points to the key ring used by the ZSS server. Then you copy the CA certificate to the Zowe App Server key store and update the Zowe App Server configuration file. +If you are going to use AT-TLS, you will need to set up TLS rule and TLS keyring. The next section will cover that information. **Note:** Bracketed values below (including the brackets) are variables. Replace them with values relevant to your organization. Always use the same value when substituting a variable that occurs multiple times. @@ -373,43 +355,11 @@ TTLSCipherParms cipher~ZSS } ``` -#### Configuring the Zowe App Server for HTTPS communication with ZSS -In the `zowe.yaml` configuration file, specify the location of the certificate. Default self signed certificates get generated during `zwe init` step in the Zowe install. -1. Open the `zowe.yaml` file. -2. In the **zowe.certificates.pem** section, add the certificate file path, type, and other variables as needed in the *zowe.certificates* variable, for example: -``` -# default certificate - certificate: - keystore: - type: PKCS12 - file: "/your-user/keystore-v2/localhost/localhost.keystore.p12" - password: "password" - alias: "localhost" - truststore: - type: PKCS12 - file: "/your-user/keystore-v2/localhost/localhost.truststore.p12" - password: "password" - pem: - key: "/your-user/keystore-v2/localhost/localhost.key" - certificate: "/your-user/keystore-v2/localhost/localhost.cer" - certificateAuthorities: "/your-user/keystore-v2/local_ca/local_ca.cer" -``` -Note: .pem files have no encryption in them so they are a security concern. Zowe by default should use .p12 files. +TODO: Below section needs to be modifed and linked configure instance directory file changed + -3. (optional - not secure) In the **components.zss.agent.http** section add the key-value pair `attls: true` with *ipAddresses* variable to enable AT-TLS, for example: -``` -zss: - enabled: true - port: 8542 - crossMemoryServerName: ZWESIS_STD - tls: false - agent: - http: - ipAddresses: ["127.0.0.1"] - attls: true -``` ### Installing additional ZSS instances After you install Zowe, you can install and configure additional instances of ZSS on the same z/OS server. You might want to do this to test different ZSS versions. @@ -425,7 +375,7 @@ The following steps assume you have installed a Zowe runtime instance (which inc 2. Create a new Zowe instance directory by following steps in [Creating and configuring the Zowe instance directory](configure-instance-directory.md). - **Note:** In the `zowe.yaml` configuration file, specify ports that are not used by the first Zowe runtime. + **Note:** In the Zowe configuration file, specify ports that are not used by the first Zowe runtime. 3. To restart the first Zowe runtime, in SDSF enter the following command: @@ -486,9 +436,9 @@ The following steps assume you have installed a Zowe runtime instance (which inc `ZIS status - Ok (name='ZWESIS_MYSRV ', cmsRC=0, description='Ok', clientVersion=2)` -## Controlling access to applications +## Controlling access to apps -You can control which applications are accessible (visible) to all Zowe desktop users, and which are accessible only to individual users. For example, you can make an application that is under development only visible to the team working on it. +You can control which apps are accessible (visible) to all Zowe desktop users, and which are accessible only to individual users. For example, you can make an app that is under development only visible to the team working on it. You control access by editing JSON files that list the apps. One file lists the apps all users can see, and you can create a file for each user. When a user logs into the desktop, Zowe determines the apps that user can see by concatenating their list with the all users list. @@ -498,40 +448,43 @@ You can also control access to the JSON files. The files are accessible directly By default, RBAC is disabled and all authenticated Zowe users can access all dataservices. To enable RBAC, follow these steps: -1. To enable RBAC, set the *components.zss.dataserviceAuthentication.rbac* variable to `true` +1. To enable RBAC, set the *components.zss.dataserviceAuthentication.rbac* and *components.app-server.dataserviceAuthentication.rbac* variables to `true` in the Zowe configuration file. -### Controlling application access for all users +### Controlling app access for all users + +**Note:** +- variable comes from Zowe configuration file. 1. Enable RBAC. 2. Navigate to the following location: ``` - $ROOT_DIR/components/app-server/share/zlux-app-server/defaults/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins + /components/app-server/share/zlux-app-server/defaults/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins ``` 3. Copy the `allowedPlugins.json` file and paste it in the following location: ``` - $ROOT_DIR/components/app-server/share/zlux-app-server/deploy/instance/ZLUX/pluginStorage + /components/app-server/share/zlux-app-server/deploy/instance/ZLUX/pluginStorage ``` 4. Open the copied `allowedPlugins.json` file and perform either of the following steps: - - To an application unavailable, delete it from the list of objects. - - To make an application available, copy an existing plugin object and specify the application's values in the new object. Identifier and version attributes are required. + - To make an app unavailable, delete it from the list of objects. + - To make an app available, copy an existing plugin object and specify the app's values in the new object. Identifier and version attributes are required. 5. [Restart the app server](configure-zowe-server.md#stopping-the-zwesvstc-proc). -### Controlling application access for individual users +### Controlling app access for individual users 1. Enable RBAC. 2. In the user's ID directory path, in the `\pluginStorage` directory, create `\org.zowe.zlux.bootstrap\plugins` directories. For example: ``` - $ROOT_DIR/components/app-server/share/zlux-app-server/deploy/instance/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins + /components/app-server/share/zlux-app-server/deploy/instance/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins ``` 3. In the `/plugins` directory, create an `allowedPlugins.json` file. You can use the default `allowedPlugins.json` file as a template by copying it from the following location: ``` - $ROOT_DIR/components/app-server/share/zlux-app-server/defaults/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins + /components/app-server/share/zlux-app-server/defaults/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins ``` -6. Open the `allowedPlugins.json` file and specify applications that user can access. For example: +6. Open the `allowedPlugins.json` file and specify apps that user can access. For example: ```json { "allowedPlugins": [ @@ -560,7 +513,7 @@ By default, RBAC is disabled and all authenticated Zowe users can access all dat ## Controlling access to dataservices To apply role-based access control (RBAC) to dataservice endpoints, you must enable RBAC for Zowe, and then use a z/OS security product such as RACF to map roles and authorities to the endpoints. After you apply RBAC, Zowe checks authorities before allowing access to the endpoints. -You can apply access control to Zowe endpoints and to your application endpoints. Zowe provides endpoints for a set of configuration dataservices and a set of core dataservices. Applications can use [configuration endpoints](../extend/extend-desktop/mvd-configdataservice.md#configuration-dataservice) to store and their own configuration and other data. Administrators can use core endpoints to [get status information](mvd-configuration.md#Administering-the-servers-and-plugins-using-an-API) from the Application Framework and ZSS servers. Any dataservice added as part of an application plugin is a service dataservice. +You can apply access control to Zowe endpoints and to your app endpoints. Zowe provides endpoints for a set of configuration dataservices and a set of core dataservices. Apps can use [configuration endpoints](../extend/extend-desktop/mvd-configdataservice.md#configuration-dataservice) to store and their own configuration and other data. Administrators can use core endpoints to [get status information](mvd-configuration.md#Administering-the-servers-and-plugins-using-an-API) from the App Framework and ZSS servers. Any dataservice added as part of an app plugin is a service dataservice. ### Defining the RACF ZOWE class If you use RACF security, take the following steps define the ZOWE class to the CDT class: @@ -695,9 +648,9 @@ The following is an example configuration for `zss-auth`, as seen in a default i } ``` -## Enabling tracing +## Enabling tracing for Zowe App Server or ZSS -To obtain more information about how a server is working, you can enable tracing within the `zowe.yaml` file via *components.app-server.logLevels* variable. +To obtain more information about how a server is working, you can enable tracing within the Zowe configuration file via *components.app-server.logLevels* or *components.zss.logLevels* variable. For more information on all loggers, check out the [Extended documentation](../extend/extend-desktop/mvd-core-loggers.md). For example: @@ -719,139 +672,49 @@ zss: All settings are optional. -### Zowe Application Server tracing - -To determine how the Zowe Application Server (`zlux-app-server`) is working, you can assign a logging level to one or more of the pre-defined logger names in the `zowe.yaml` file for the App server component (*components.app-server*). - -The log prefix for the Zowe Application Server is **_zsf**, which is used by the server framework. (Applications and plugins that are attached to the server do not use the **_zsf** prefix.) - -The following are the logger names that you can specify: - -**_zsf.bootstrap** -Logging that pertains to the startup of the server. - -**_zsf.auth** -Logging for network calls that must be checked for authentication and authorization purposes. - -**_zsf.static** -Logging of the serving of static files (such as images) from an application's `/web` folder. - -**_zsf.child** -Logging of child processes, if any. - -**_zsf.utils** -Logging for miscellaneous utilities that the server relies upon. - -**_zsf.proxy** -Logging for proxies that are set up in the server. - -**_zsf.install** -Logging for the installation of plugins. - -**_zsf.apiml** -Logging for communication with the api mediation layer. - -**_zsf.routing** -Logging for dispatching network requests to plugin dataservices. - -**_zsf.network** -Logging for the HTTPS server status (connection, ports, IP, and so on) - -### Log levels - -The log levels are: +## Zowe App Framework logging - - SEVERE = 0, - - WARNING = 1, - - INFO = 2, - - FINE = 3, - - FINER = 4, - - FINEST = 5 +The Zowe App Framework log files contain processing messages and statistics. The log files are generated the specified log location (*zowe.logDirectory*) in the Zowe configuration file: -FINE, FINER, and FINEST are log levels for debugging, with increasing verbosity. - -### Enabling tracing for ZSS - -To increase logging for ZSS, you can assign a logging level (an integer value greater than zero) to one or more of the pre-defined logger names in the `zowe.yaml` file for the ZSS component (*components.zss*). - -A higher value specifies greater verbosity. - -The log prefix for ZSS is **_zss**. The following are the logger names that you can specify: - -**_zss.traceLevel:** -Controls general server logging verbosity. - -**_zss.fileTrace:** -Logs file serving behavior (if file serving is enabled). - -**_zss.socketTrace:** -Logs general TCP Socket behavior. - -**_zss.httpParseTrace:** -Logs parsing of HTTP messages. - -**_zss.httpDispatchTrace:** -Logs dispatching of HTTP messages to dataservices. - -**_zss.httpHeadersTrace:** -Logs parsing and setting of HTTP headers. - -**_zss.httpSocketTrace:** -Logs TCP socket behavior for HTTP. - -**_zss.httpCloseConversationTrace:** -Logs HTTP behavior for when an HTTP conversation ends. - -**_zss.httpAuthTrace:** -Logs behavior for session security. - -When you are finished specifying the settings, save the `server.json` file. - - -## Zowe Application Framework logging - -The Zowe Application Framework log files contain processing messages and statistics. The log files are generated the specified log location (*zowe.logDirectory*) in the `zowe.yaml` file: - -- Zowe Application Server: `{your-location}/appServer-yyyy-mm-dd-hh-mm.log` +- Zowe App Server: `{your-location}/appServer-yyyy-mm-dd-hh-mm.log` - ZSS: `{your-location}/zssServer-yyyy-mm-dd-hh-mm.log` The logs are timestamped in the format yyyy-mm-dd-hh-mm and older logs (by default, last five are retained) are deleted when a new log is created at server startup. - ### Controlling the logging location -The log information is written to a file and to the screen. (On Windows, logs are written to a screen only.) +The log information is written to a file and to the screen. #### ZLUX_NODE_LOG_DIR and ZSS_LOG_DIR environment variables -To control where the information is logged, use the environment variable *ZLUX_NODE_LOG_DIR*, for the Zowe Application Server, and *ZSS_LOG_DIR*, for ZSS. While these variables are intended to specify a directory, if you specify a location that is a file name, Zowe will write the logs to the specified file instead (for example: `/dev/null` to disable logging). +To control where the information is logged, use the environment variable *ZLUX_NODE_LOG_DIR*, for the Zowe App Server, and *ZSS_LOG_DIR*, for ZSS. While these variables are intended to specify a directory, if you specify a location that is a file name, Zowe will write the logs to the specified file instead (for example: `/dev/null` to disable logging). When you specify the environment variables *ZLUX_NODE_LOG_DIR* and *ZSS_LOG_DIR* and you specify directories rather than files, Zowe will timestamp the logs and delete the older logs that exceed the *ZLUX_NODE_LOGS_TO_KEEP* threshold. #### ZLUX_NODE_LOG_FILE and ZSS_LOG_FILE environment variables -If you set the log file name for the Zowe Application Server by setting the *ZLUX_NODE_LOG_FILE* environment variable, or if you set the log file for ZSS by setting the *ZSS_LOG_FILE* environment variable, there will only be one log file, and it will be overwritten each time the server is launched. +If you set the log file name for the Zowe App Server by setting the *ZLUX_NODE_LOG_FILE* environment variable, or if you set the log file for ZSS by setting the *ZSS_LOG_FILE* environment variable, there will only be one log file, and it will be overwritten each time the server is launched. **Note**: When you set the *ZLUX_NODE_LOG_FILE* or *ZSS_LOG_FILE* environment variables, Zowe will not override the log names, set a timestamp, or delete the logs. If the directory or file cannot be created, the server will run (but it might not perform logging properly). ### Retaining logs -By default, the last five logs are retained. To specify a different number of logs to retain, set *ZLUX_NODE_LOGS_TO_KEEP* (Zowe Application Server logs) or *ZSS_LOGS_TO_KEEP* (ZSS logs) to the number of logs that you want to keep. For example, if you set *ZLUX_NODE_LOGS_TO_KEEP* to 10, when the eleventh log is created, the first log is deleted. +By default, the last five logs are retained. To specify a different number of logs to retain, set *ZLUX_NODE_LOGS_TO_KEEP* (Zowe App Server logs) or *ZSS_LOGS_TO_KEEP* (ZSS logs) to the number of logs that you want to keep. For example, if you set *ZLUX_NODE_LOGS_TO_KEEP* to 10, when the eleventh log is created, the first log is deleted. ## Administering the servers and plugins using an API -You can use a REST API to retrieve and edit Zowe Application Server and ZSS server configuration values, and list, add, update, and delete plugins. If an administrator has configured Zowe to [use RBAC](https://docs.zowe.org/stable/user-guide/mvd-configuration.html#applying-role-based-access-control-to-dataservices), they must authorize you to access the endpoints. +You can use a REST API to retrieve and edit Zowe App Server and ZSS server configuration values, and list, add, update, and delete plugins. If an administrator has configured Zowe to [use RBAC](https://docs.zowe.org/stable/user-guide/mvd-configuration.html#applying-role-based-access-control-to-dataservices), they must authorize you to access the endpoints. The API returns the following information in a JSON response: | API | Description | | --------------------------------------------------------- | ------------------------------------------------------------ | -| /server (GET) | Returns a list of accessible server endpoints for the Zowe Application Server. | -| /server/config (GET) | Returns the Zowe Application Server configuration from the `zluxserver.json` file. | -| /server/log (GET) | Returns the contents of the Zowe Application Server log file. | -| /server/loglevels (GET) | Returns the verbosity levels set in the Zowe Application Server logger. | -| /server/environment (GET) | Returns Zowe Application Server environment information, such as the operating system version, node server version, and process ID. | -| /server/reload (GET) | Reloads the Zowe Application Server. Only available in cluster mode. | +| /server (GET) | Returns a list of accessible server endpoints for the Zowe App Server. | +| /server/config (GET) | Returns the Zowe App Server configuration from the `zluxserver.json` file. | +| /server/log (GET) | Returns the contents of the Zowe App Server log file. | +| /server/loglevels (GET) | Returns the verbosity levels set in the Zowe App Server logger. | +| /server/environment (GET) | Returns Zowe App Server environment information, such as the operating system version, node server version, and process ID. | +| /server/reload (GET) | Reloads the Zowe App Server. Only available in cluster mode. | | /server/agent (GET) | Returns a list of accessible server endpoints for the ZSS server. | | /server/agent/config (GET) | Returns the ZSS server configuration from the `zluxserver.json` file. | | /server/agent/log (GET) | Returns the contents of the ZSS log file. | From bf9f8dfbde5522f69adfd235688f18e3c01c59dc Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Tue, 5 Apr 2022 13:52:03 -0400 Subject: [PATCH 14/17] Simplify adv config by pointing to json schema. Reorder some sections to show what seems like the most popular content first. Update the logging section Signed-off-by: 1000TurquoisePogs --- docs/user-guide/mvd-configuration.md | 176 +++++++++++++-------------- 1 file changed, 85 insertions(+), 91 deletions(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index d15858feff..3a20098ac2 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -6,36 +6,49 @@ When you install Zowe™, the App Framework is configured as a Mediation Lay You can modify the Zowe App Server and Zowe System Services (ZSS) configuration, as needed, or configure connections for the Terminal app plugins. -## Configuring the framework as a Mediation Layer client +## Accessing the App Server -When you install Zowe v1.8.0 or later, the App Server automatically registers with the Mediation Layer. +When the server is enabled and given a port within [the configuration file](configure-instance-directory.md), the App server will print a message ZWED0031I in the log output. At that time, it is ready to accept network communication. When using the API Mediation Layer (recommended), app-server URLs should be reached from the Gateway, and you should additionally wait for the message ZWEAM000I for the Gateway to be ready. -For earlier releases, you must register the App Server with the Mediation Layer manually. Refer to previous release documentation for more information. +When Zowe is ready, the app-server can be found at `https://:/zlux/ui/v1` -The App server utilizes the certificates set up for use by all of Zowe as specified in the Zowe configuration file. See [Zowe certificate configuration section](../user-guide/configure-certificates.md#configuring-zowe-certificates) for more information. +(Not recommended): If the mediation layer is not used, or you need to contact the app-server directly, the ZWED0031I message states which port it is accessible from, though generally it will be the same value as specified within `components.app-server.port`. In that case, the server would be available at `https://:/` -### Accessing the App Server +### Accessing the Desktop -When the server is enabled in the configuration file, the App server is accessible via the following URL. ZWED0031I message code can tell us when the App server is ready to be accessed. +When the app-server and gateway are ready, the Desktop can be accessed from the API Mediation Layer Gateway, such as -Recommended: To access the App Server (Zowe Desktop) through the Mediation Layer, use the Mediation Layer gateway server hostname and port. +`https://:/zlux/ui/v1/`, which will redirect to `https://:/zlux/ui/v1/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` -`https://:/zlux/ui/v1/` or -`https://:/zlux/ui/v1/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` +(Not recommended): If the mediation layer is not used, the Desktop will be accessible from the app-server directly at `/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` -(Not recommended): To access the App Server directly, use the App server hostname and port. +You should be accessing the App server via the Gateway port, but the App server still needs a port assigned to it which is the value of the *components.app-server.port* variable in the Zowe configuration file, -`https://:` or -`https://:/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` +TODO: Above linked file needs to be changed -You should be accessing the App server via the Gateway port, but the App server still needs a port assigned to it which is the value of the *components.app-server.port* variable in the Zowe configuration file, see [Creating and configuring the Zowe instance directory](configure-instance-directory.md). +## Accessing ZSS +TODO -TODO: Above linked file needs to be changed +## Configuration file + +### app-server configuration + +The app-server uses the Zowe server configuration file for customizing server behavior. For a full list of parameters, requirements, and descriptions, see [the json-schema document for the app-server](https://github.com/zowe/zlux/blob/v2.x/staging/schemas/zlux-config-schema.json) which describes attributes that can be specified within the configuration file section `components.app-server` +### zss configuration +ZSS shares some parameters in common with the app-server, so you can consult the above json-schema document to find out which parameters are valid within `components.zss` of the Zowe configuration file. However, some parameters within the app-server schema are not used by ZSS, such as the `node` section. A ZSS-centric schema will be available soon. + +## Environment variables + +In the latest version of Zowe, `instance.env` is no longer used. However, some environment variables that could be specified within v1 can still be set within v2 in the `zowe.environments` section of the server configuration file. Environment variables starting with `ZWED_` map to values that can be specified within `components.app-server` and `components.zss` so they are redundant, but you can refer to the above json-schema document to see which values are useful or deprecated. + + +## Configuring the framework as a Mediation Layer client -The port number for the API Mediation Layer is the value of the *components.gateway.port* variable in the same file. +The App Server and ZSS automatically register to the API Mediation Layer when present. +If this is not desired, it can be disabled by setting the properties `components.app-server.mediationLayer.server.enabled=false` for app-server and `components.zss.mediationLayer.enabled=false` for ZSS. ## Setting up terminal app plugins @@ -43,7 +56,8 @@ Follow these optional steps to configure the default connection to open for the ### Setting up the TN3270 mainframe terminal app plugin -`_defaultTN3270.json` is a file in `tn3270-ng2/`, which is deployed during setup. Within this file, you can specify the following parameters to configure the terminal connection: +The file `_defaultTN3270.json` within the `tn3270-ng2` app folder `/config/storageDefaults/sessions/` is deployed to the [configuration dataservice](../extend/extend-desktop/mvd-configdataservice.md) when the app-server runs for the first time. This file is used to tell the terminal what host to connect to by default. If you'd like to customize this default, you can edit the file directly within the configuration dataservice `/org.zowe.terminal.tn3270/sessions/_defaultTN3270.json`. Or you can open the app, customize a session within the UI, click the save icon (floppy icon) and then copy that file from `//org.zowe.terminal.tn3270/sessions/_defaultTN3270.json` to `/org.zowe.terminal.tn3270/sessions/_defaultTN3270.json`. Either way, you will see a file with the following properties: + ``` "host": "port": @@ -51,9 +65,11 @@ Follow these optional steps to configure the default connection to open for the type: <"telnet" or "tls"> } ``` + ### Setting up the VT Terminal app plugin -`_defaultVT.json` is a file in `vt-ng2/`, which is deployed during setup. Within this file, you can specify the following parameters to configure the terminal connection: +The file `_defaultVT.json` within the `vt-ng2` app folder `/config/storageDefaults/sessions/` is deployed to the [configuration dataservice](../extend/extend-desktop/mvd-configdataservice.md) when the app-server runs for the first time. This file is used to tell the terminal what host to connect to by default. If you'd like to customize this default, you can edit the file directly within the configuration dataservice `/org.zowe.terminal.vt/sessions/_defaultVT.json`. Or you can open the app, customize a session within the UI, click the save icon (floppy icon) and then copy that file from `//org.zowe.terminal.vt/sessions/_defaultVT.json` to `/org.zowe.terminal.vt/sessions/_defaultVT.json`. Either way, you will see a file with the following properties: + ``` "host": "port": @@ -62,14 +78,6 @@ Follow these optional steps to configure the default connection to open for the } ``` -## Configuration file - -For convenience, the App Server and ZSS share nearly identical configurations and read from the Zowe configuration file (via `components.app-server` and `components.zss`). Some values of configuration can be specified in the App server or ZSS sections. It is possible for each of these servers to read each others' sections to learn about their configuration. - -## Environment variables - -In Zowe V1, environment variables were originally specified in `instance.env`. In V2, while most variables can be customized in corresponding component sections of the Zowe configuration file, additional environment variables can be specified in `zowe.environments` section. - ## Network configuration **Note:** The following attributes are to be defined in the Zowe configuration file. @@ -137,19 +145,8 @@ When running, the App Server will access the server's settings and read or modif - Group: Multiple users can be associated into one group, so that settings are shared among them. - User: When authenticated, users have their own settings and storage for the Apps that they use. -These directories dictate where the [Configuration Dataservice](https://github.com/zowe/zlux/wiki/Configuration-Dataservice) will store content. +These directories dictate where the Configuration Dataservice will store content. For more information, see the [Configuration Dataservice documentation](..//extend-desktop/mvd-configdataservice.md) -### Directories example -``` -// All paths relative to zlux-app-server/lib -// In real installations, these values will be configured during the install. - "productDir":"../defaults", - "siteDir":"/home/myuser/.zowe/workspace/app-server/site", - "instanceDir":"/home/myuser/.zowe/workspace/app-server", - "groupsDir":"/home/myuser/.zowe/workspace/app-server/groups", - "usersDir":"/home/myuser/.zowe/workspace/app-server/users", - -``` ### Old defaults Prior to Zowe release 2.0.0, the location of the configuration directories were initialized to be within the `` folder unless otherwise customized. 2.0.0 does have backwards compatibility for the existence of these directories, but `` folder no longer exists, so they should be migrated to match the ones specified in the Zowe configuration file. @@ -164,12 +161,62 @@ Prior to Zowe release 2.0.0, the location of the configuration directories were ## App plugin configuration -The App server will load plugins from extensions and components based upon their enabled status in Zowe configuration. The server caches knowledge of these plugins in the `/app-server/plugins` folder. This location can be customized with the *components.app-server.pluginsDir* variable in the Zowe configuration file. +The App framework will load plugins from Components such as extensions based upon their enabled status in Zowe configuration. The server caches knowledge of these plugins in the `/app-server/plugins` folder. This location can be customized with the *components.app-server.pluginsDir* variable in the Zowe configuration file. ## Logging configuration For more information, see [Logging Utility](../extend/extend-desktop/mvd-logutility.md). +### Enabling tracing + +To obtain more information about how a server is working, you can enable tracing within the Zowe configuration file via *components.app-server.logLevels* or *components.zss.logLevels* variable. For more information on all loggers, check out the [Extended documentation](../extend/extend-desktop/mvd-core-loggers.md). + +For example: + +``` +app-server: + {...} + logLevels: + _zsf.routing: 0 + _zsf.install: 0 +``` + +``` +zss: + {...} + logLevels: + _zss.traceLevel: 0 + _zss.fileTrace: 1 +``` + +All settings are optional. + +### Log files + +The app-server and zss will create log files containing processing messages and statistics. The log files are generated within the log directory specified within the Zowe configuration file (`zowe.logDirectory`). The filename patterns are: + +- App Server: `/appServer-yyyy-mm-dd-hh-mm.log` +- ZSS: `/zssServer-yyyy-mm-dd-hh-mm.log` + +#### Retaining logs + +By default, the last five log files are retained. You can change this by setting environment variables within the `zowe.environments` section of the Zowe server configuration file. To specify a different number of logs to retain, set `ZWED_NODE_LOGS_TO_KEEP` for app-server logs, or *ZWES_LOGS_TO_KEEP* for zss logs. For example, if you set `ZWED_NODE_LOGS_TO_KEEP` to 10, when the eleventh log is created, the first log is deleted. + +#### Controlling the logging location + +At minimum, the log information for both app-server and zss are written to STDOUT such that messages are visible in the terminal that starts Zowe and when on z/OS, the STC job log. + +By default, both servers additionally log to files and the location of these files can be changed or logging to them can be disabled. +The following environment variables can be used to customize the app-server and zss log locations by setting the values within the `zowe.environments` section of the Zowe configuration file. + +* `ZWED_NODE_LOG_DIR`: Overrides the zowe configuration file value of `zowe.logDirectory` for app-server, but keeps the default filenames. +* `ZWES_LOG_DIR`: Overrides the zowe configuration file value of `zowe.logDirectory` for zss, but keeps the default filenames. +* `ZWED_NODE_LOG_FILE`: Specifies the full path to the file where logs will be written from app-server. This overrides both `ZWED_NODE_LOG_DIR` and `zowe.logDirectory`. If the path is `/dev/null` then no log file will be written. This option does not timestamp logs or keep multiple of them. +* `ZWES_LOG_FILE`: Specifies the full path to the file where logs will be written from zss. This overrides both `ZWES_LOG_DIR` and `zowe.logDirectory`. If the path is `/dev/null` then no log file will be written. This option does not timestamp logs or keep multiple of them. + +If the directory or file specified cannot be created, the server will run (but it might not perform logging properly). + + ## ZSS configuration Running ZSS requires a Zowe configuration file configuration that is similar to the one used for the Zowe App Server (by structure and property names). The attributes that are needed for ZSS (*components.zss*) at minimum, are: *port*, *crossMemoryServerName*. @@ -648,59 +695,6 @@ The following is an example configuration for `zss-auth`, as seen in a default i } ``` -## Enabling tracing for Zowe App Server or ZSS - -To obtain more information about how a server is working, you can enable tracing within the Zowe configuration file via *components.app-server.logLevels* or *components.zss.logLevels* variable. For more information on all loggers, check out the [Extended documentation](../extend/extend-desktop/mvd-core-loggers.md). - -For example: - -``` -app-server: - {...} - logLevels: - _zsf.routing: 0 - _zsf.install: 0 -``` - -``` -zss: - {...} - logLevels: - _zss.traceLevel: 0 - _zss.fileTrace: 1 -``` - -All settings are optional. - -## Zowe App Framework logging - -The Zowe App Framework log files contain processing messages and statistics. The log files are generated the specified log location (*zowe.logDirectory*) in the Zowe configuration file: - -- Zowe App Server: `{your-location}/appServer-yyyy-mm-dd-hh-mm.log` -- ZSS: `{your-location}/zssServer-yyyy-mm-dd-hh-mm.log` - -The logs are timestamped in the format yyyy-mm-dd-hh-mm and older logs (by default, last five are retained) are deleted when a new log is created at server startup. - -### Controlling the logging location - -The log information is written to a file and to the screen. - -#### ZLUX_NODE_LOG_DIR and ZSS_LOG_DIR environment variables - -To control where the information is logged, use the environment variable *ZLUX_NODE_LOG_DIR*, for the Zowe App Server, and *ZSS_LOG_DIR*, for ZSS. While these variables are intended to specify a directory, if you specify a location that is a file name, Zowe will write the logs to the specified file instead (for example: `/dev/null` to disable logging). - -When you specify the environment variables *ZLUX_NODE_LOG_DIR* and *ZSS_LOG_DIR* and you specify directories rather than files, Zowe will timestamp the logs and delete the older logs that exceed the *ZLUX_NODE_LOGS_TO_KEEP* threshold. - -#### ZLUX_NODE_LOG_FILE and ZSS_LOG_FILE environment variables - -If you set the log file name for the Zowe App Server by setting the *ZLUX_NODE_LOG_FILE* environment variable, or if you set the log file for ZSS by setting the *ZSS_LOG_FILE* environment variable, there will only be one log file, and it will be overwritten each time the server is launched. - -**Note**: When you set the *ZLUX_NODE_LOG_FILE* or *ZSS_LOG_FILE* environment variables, Zowe will not override the log names, set a timestamp, or delete the logs. - -If the directory or file cannot be created, the server will run (but it might not perform logging properly). - -### Retaining logs -By default, the last five logs are retained. To specify a different number of logs to retain, set *ZLUX_NODE_LOGS_TO_KEEP* (Zowe App Server logs) or *ZSS_LOGS_TO_KEEP* (ZSS logs) to the number of logs that you want to keep. For example, if you set *ZLUX_NODE_LOGS_TO_KEEP* to 10, when the eleventh log is created, the first log is deleted. ## Administering the servers and plugins using an API You can use a REST API to retrieve and edit Zowe App Server and ZSS server configuration values, and list, add, update, and delete plugins. If an administrator has configured Zowe to [use RBAC](https://docs.zowe.org/stable/user-guide/mvd-configuration.html#applying-role-based-access-control-to-dataservices), they must authorize you to access the endpoints. From 36d9d3d54a33ceccae347280c151a55c105e395d Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Thu, 7 Apr 2022 12:56:13 -0400 Subject: [PATCH 15/17] Update mvd-configuration.md --- docs/user-guide/mvd-configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 3a20098ac2..81acb6206f 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -12,7 +12,7 @@ When the server is enabled and given a port within [the configuration file](conf When Zowe is ready, the app-server can be found at `https://:/zlux/ui/v1` -(Not recommended): If the mediation layer is not used, or you need to contact the app-server directly, the ZWED0031I message states which port it is accessible from, though generally it will be the same value as specified within `components.app-server.port`. In that case, the server would be available at `https://:/` +(Not recommended): If the API Mediation Layer is not used, or you need to contact the App server directly, the ZWED0031I message states which port it is accessible from, though generally it will be the same value as specified within `components.app-server.port`. In that case, the server would be available at `https://:/` ### Accessing the Desktop @@ -20,7 +20,7 @@ When the app-server and gateway are ready, the Desktop can be accessed from the `https://:/zlux/ui/v1/`, which will redirect to `https://:/zlux/ui/v1/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` -(Not recommended): If the mediation layer is not used, the Desktop will be accessible from the app-server directly at `/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` +(Not recommended): If the mediation layer is not used, the Desktop will be accessible from the App server directly at `/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` You should be accessing the App server via the Gateway port, but the App server still needs a port assigned to it which is the value of the *components.app-server.port* variable in the Zowe configuration file, @@ -48,7 +48,7 @@ In the latest version of Zowe, `instance.env` is no longer used. However, some e ## Configuring the framework as a Mediation Layer client The App Server and ZSS automatically register to the API Mediation Layer when present. -If this is not desired, it can be disabled by setting the properties `components.app-server.mediationLayer.server.enabled=false` for app-server and `components.zss.mediationLayer.enabled=false` for ZSS. +If this is not desired, registration can disabled by setting the properties `components.app-server.mediationLayer.server.enabled=false` for app-server and `components.zss.mediationLayer.enabled=false` for ZSS. ## Setting up terminal app plugins From 9e4ba2eac2f6d39b20afe88289979912006fb4fb Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Thu, 7 Apr 2022 14:25:31 -0400 Subject: [PATCH 16/17] Fix zss instance setup -> zis. Clarify AT-TLS use. Describe zss 64 bit mode Signed-off-by: 1000TurquoisePogs --- docs/user-guide/mvd-configuration.md | 128 +++++++++++---------------- 1 file changed, 53 insertions(+), 75 deletions(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 81acb6206f..81c73ffd52 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -245,20 +245,50 @@ zss: attls: true ``` -### Configuring ZSS for AT-TLS +### ZSS 64 or 31 bit modes -By default, ZSS is enabled in HTTPS and doesn't require an advanced configuration outside the required attributes in the recommended example above. +Two versions of ZSS are included in Zowe, a 64 bit version and a 31 bit version. It is recommended to run the 64 bit version to conserve shared system memory but you must match the ZSS version with the version your ZSS plugins support. Official Zowe distributions contain plugins that support both 64 bit and 31 bit, but extensions may only support one or the other. -If you want to use RACF or AT-TLS (which requires ZSS to be in HTTP mode), you must have a basic knowledge of your security product and you must have Policy Agent configured. For more information on [AT-TLS](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.halx001/transtls.htm) and [Policy Agent](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2.halz002/pbn_pol_agnt.htm), see the [z/OS Knowledge Center](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2/en/homepage.html). +#### Verifying which ZSS mode is in use -You must have the authority to alter security definitions related to certificate management, and you must be authorized to work with and update the Policy Agent. +You can check which version of ZSS you are running by looking at the logs. At startup, the message ZWES1013I states which mode is being used, for example: -If you are going to use AT-TLS, you will need to set up TLS rule and TLS keyring. The next section will cover that information. +`ZWES1013I ZSS Server has started. Version 2.0.0 64-bit` + +Or + +`ZWES1013I ZSS Server has started. Version 2.0.0 31-bit` + +#### Verifying which ZSS mode plugins support + +You can check if a ZSS plugin supports 64 bit or 31 bit ZSS by reading the pluginDefinition.json file of the plugin. +In each component or extension you have, its manifest file will state if there are `appFw` plugin entries. +In each folder referenced by the `appFw` section, you will see a pluginDefinition.json file. +Within that file, if you see a section that says `type: 'service'`, then you can check its ZSS mode support. +If the service has the property `libraryName64`, then it supports 64 bit. If it says `libraryName31`, then it supports 31 bit. Both may exist if it supports both. If it instead only contains `libraryName`, this is ambigious and deprecated, and most likely that plugin only supports 31 bit ZSS. A plugin only supporting 31 bit ZSS must be recompiled for 64 bit support, so you must contact the developers to accomplish that. + +Example: [the sample angular app supports both 31 bit and 64 bit zss](https://github.com/zowe/sample-angular-app/blob/083855582e8a82cf48abc21e15fa20bd59bfe180/pluginDefinition.json#L50-L53) + +#### Setting ZSS 64 bit or 31 bit mode + +You can switch between ZSS 64 bit and 31 bit mode by setting the value `components.zss.agent.64bit` to true or false in the Zowe configuration file. The value will not take effect until next server restart. + +## Using AT-TLS in the App Framework + +By default, both ZSS and the App server use HTTPS regardless of platform. However, some may wish to use AT-TLS on z/OS as an alternative way to provide HTTPS. +In order to do this, the servers must run in HTTP mode instead, and utilize AT-TLS for HTTPS. **The servers should never use HTTP without AT-TLS, it would be insecure**. +If you want to use AT-TLS, you must have a basic knowledge of your security product and you must have Policy Agent configured. For more information on [AT-TLS](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.halx001/transtls.htm) and [Policy Agent](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2.halz002/pbn_pol_agnt.htm), see the [z/OS Knowledge Center](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2/en/homepage.html). + +There are a few requirements to working with AT-TLS: +* You must have the authority to alter security definitions related to certificate management, and you must be authorized to work with and update the Policy Agent. +* AT-TLS needs a TLS rule and keyring. The next section will cover that information. **Note:** Bracketed values below (including the brackets) are variables. Replace them with values relevant to your organization. Always use the same value when substituting a variable that occurs multiple times. -#### Creating certificates and key ring for the ZSS server using RACF -In this step you will create a root CA certificate and a ZSS server certificate signed by the CA certificate. Next you create a key ring owned by the ZSS server with the certificates attached. +### Creating AT-TLS certificates and keyring using RACF +In the following commands and examples you will create a root CA certificate and a server certificate signed by it. These will be placed within a keyring which is owned by the user that runs the Zowe server. +**Note: These actions can be done for various Zowe servers, but in these examples we set up ZSS for AT-TLS. You can subsitute ZSS for another server if desired.** + Key variables: @@ -273,8 +303,8 @@ Key variables: | `[output_dataset_name]` | | **Note**: -- `[server_userid]` must be the ZSS server user ID. -- `[server_common_name]` must be the ZSS server host name. +- `[server_userid]` must be the server user ID, such as the STC user. +- `[server_common_name]` must be the z/OS hostname that runs Zowe 1. Enter the following RACF command to generate a CA certificate: ``` @@ -335,13 +365,13 @@ Key variables: **Note**: These sample commands use the FACILTY class to manage certificate related authorizations. You can also use the RDATALIB class, which offers granular control over the authorizations. -7. Enter the following RACF command to export the CA certificate to a dataset so it can be imported by the Zowe App Server: +7. Enter the following RACF command to export the CA certificate to a dataset so it can be imported by the Zowe server: ``` RACDCERT CERTAUTH EXPORT(LABEL('[ca_label]')) + DSN('[output_dataset_name]') FORMAT(CERTB64) ``` -#### Defining the AT-TLS rule +### Defining the AT-TLS rule To define the AT-TLS rule, use the sample below to specify values in your AT-TLS Policy Agent Configuration file: ``` @@ -403,82 +433,30 @@ TTLSCipherParms cipher~ZSS ``` +## Using multiple ZIS instances +When you install Zowe, it is ready to be used for 1 instance of each component. However, ZIS can have a one-to-many relationship with the Zowe webservers, and so you may wish to have more than one copy of ZIS for testing or to handle different groups of ZIS plugins. -TODO: Below section needs to be modifed and linked configure instance directory file changed - - - -### Installing additional ZSS instances -After you install Zowe, you can install and configure additional instances of ZSS on the same z/OS server. You might want to do this to test different ZSS versions. - -The following steps assume you have installed a Zowe runtime instance (which includes ZSS), and that you are installing a second runtime instance to install an additional ZSS. - -1. To stop the installed Zowe runtime, in SDSF enter the following command: - - ``` - /C ${ZOWE_PREFIX}${ZOWE_INSTANCE}SV - ``` - Where ZOWE_PREFIX and ZOWE_INSTANCE are specified in your configuration (and default to ZWE and 1) - -2. Create a new Zowe instance directory by following steps in [Creating and configuring the Zowe instance directory](configure-instance-directory.md). +The following steps can be followed to point a Zowe instance at a particular ZIS server. - **Note:** In the Zowe configuration file, specify ports that are not used by the first Zowe runtime. +1. [Create a copy of the ZIS server](https://docs.zowe.org/stable/user-guide/configure-xmem-server). You could run multiple copies of the same code by having different STC JCLs pointing to the same LOADLIB, or run different copies of ZIS by having JCLs pointing to different LOADLIBs. -3. To restart the first Zowe runtime, in SDSF enter the following command: - - ``` - /S ZWESVSTC,INSTANCE='$INSTANCE_DIR' - ``` - - Where `$INSTANCE_DIR` is the Zowe instance directory. - -4. To specify a name for the new ZSS instance, follow these steps: - - 1. Copy the PROCLIB member JCL named ZWESISTC that was installed with the new runtime. - - 2. Rename the copy to uniquely identify it as the JCL that starts the new ZSS, for example ZWESIS02. - - 3. Edit the JCL, and in the `NAME` parameter specify a unique name for the cross-memory server, for example: +2. Edit the JCL of the ZIS STC. In the `NAME` parameter specify a unique name for the ZIS server, for example: ``` //ZWESIS02 PROC NAME='ZWESIS_MYSRV',MEM=00,RGN=0M ``` - Where `ZWESIS_MYSRV` is the unique name of the new ZSS. + Where `ZWESIS_MYSRV` is the unique name of the new ZIS. + +3. [Start the new ZIS](https://docs.zowe.org/stable/user-guide/configure-xmem-server#starting-and-stopping-the-cross-memory-server-on-zos) with whatever PROCLIB name was chosen. -5. To start the new ZSS, in SDSF enter the following command: +4. [Stop the Zowe instance you wish to point to the ZIS server](https://docs.zowe.org/stable/user-guide/stop-zowe-zos) - ``` - /S ZWESIS02 - ``` +5. Locate the zowe configuration file for the Zowe instance, and edit the parameter `components.zss.privilegedServerName` to match the name of the ZIS STC name chosen, such as `ZWESIS_MYSRV` -6. Make sure that the TSO user ID that runs the first ZSS started task also runs the new ZSS started task. The default ID is ZWESVUSR. - -7. In the new ZSS `server.json` configuration file, add a `"privilegedServerName"` parameter and specify the new ZSS name, for example: - - ``` - "productDir":"../defaults", - // All paths relative to zlux-app-server/bin - // In real installations, these values will be configured during the install. - "productDir":"../defaults", - "siteDir":"../deploy/site", - "instanceDir":"../deploy/instance", - "groupsDir":"../deploy/instance/groups", - "usersDir":"../deploy/instance/users", - "pluginsDir":"../defaults/plugins", - "privilegedServerName":"ZWESIS_MYSRV", - "dataserviceAuthentication": { ... } - ``` - - **Note:** The instance location of `server.json` is `$INSTANCE_DIR/workspace/app-server/serverConfig/server.json`, and the defaults are stored in `$ROOT_DIR/components/app-server/share/zlux-app-server/defaults/serverConfig/server.json` - -8. To start the new Zowe runtime, in SDSF enter the following command: - - ``` - /S ZWESVSTC,INSTANCE='$ZOWE_INSTANCE_DIR' - ``` +6. [Restart the Zowe instance](https://docs.zowe.org/stable/user-guide/configure-zowe-server#step-3-launch-the-zwesvstc-started-task) -9. To verify that the new cross-memory server is being used, check for the following messages in the `ZWESVSTC` server job log: +7. Verify that the new ZIS server is being used by checking for the following messages in the `ZWESLSTC` server job log: `ZIS status - Ok (name='ZWESIS_MYSRV ', cmsRC=0, description='Ok', clientVersion=2)` From 69c7abbe340e340a4668066bb4bb30db57b49d1b Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Mon, 18 Apr 2022 14:00:13 +0000 Subject: [PATCH 17/17] Fixes from Lenny's review Fixes from Lenny's review Signed-off-by: 1000TurquoisePogs --- docs/user-guide/mvd-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 81c73ffd52..79a3205b43 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -145,7 +145,7 @@ When running, the App Server will access the server's settings and read or modif - Group: Multiple users can be associated into one group, so that settings are shared among them. - User: When authenticated, users have their own settings and storage for the Apps that they use. -These directories dictate where the Configuration Dataservice will store content. For more information, see the [Configuration Dataservice documentation](..//extend-desktop/mvd-configdataservice.md) +These directories dictate where the Configuration Dataservice will store content. For more information, see the [Configuration Dataservice documentation](../extend-desktop/mvd-configdataservice.md) ### Old defaults Prior to Zowe release 2.0.0, the location of the configuration directories were initialized to be within the `` folder unless otherwise customized. 2.0.0 does have backwards compatibility for the existence of these directories, but `` folder no longer exists, so they should be migrated to match the ones specified in the Zowe configuration file. @@ -675,7 +675,7 @@ The following is an example configuration for `zss-auth`, as seen in a default i ## Administering the servers and plugins using an API -You can use a REST API to retrieve and edit Zowe App Server and ZSS server configuration values, and list, add, update, and delete plugins. If an administrator has configured Zowe to [use RBAC](https://docs.zowe.org/stable/user-guide/mvd-configuration.html#applying-role-based-access-control-to-dataservices), they must authorize you to access the endpoints. +You can use a REST API to retrieve and edit Zowe App Server and ZSS server configuration values, and list, add, update, and delete plugins. If an administrator has configured Zowe to [use RBAC](https://docs.zowe.org/stable/user-guide/mvd-configuration.html#controlling-access-to-dataservices), they must authorize you to access the endpoints. The API returns the following information in a JSON response: