From 8f96df29e6801270c4486de5648934c03ede3fb1 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Mon, 17 Nov 2025 15:37:13 +0530 Subject: [PATCH 01/57] Dividing mvd-configuration.md Signed-off-by: arooshlele --- docs/user-guide/accessing-zss.md | 0 ...ng-the-servers-and-plugins-using-an-api.md | 0 docs/user-guide/app-plugin-configuration.md | 0 docs/user-guide/configuration-directories.md | 0 docs/user-guide/configuration-file.md | 0 ...e-framework-as-a-mediation-layer-client.md | 0 docs/user-guide/controlling-access-to-apps.md | 0 .../controlling-access-to-dataservices.md | 0 .../customizing-security-plugins.md | 0 docs/user-guide/logging-configuration.md | 0 .../managing-cluster-mode-for-app-server.md | 0 docs/user-guide/mvd-configuration.md | 495 ------------------ docs/user-guide/network-configuration.md | 89 ++++ .../setting-up-terminal-app-plugins.md | 28 + .../using-multiple-zis-instances.md | 0 docs/user-guide/zss-configuration-1.md | 0 sidebars.js | 23 +- 17 files changed, 139 insertions(+), 496 deletions(-) create mode 100644 docs/user-guide/accessing-zss.md create mode 100644 docs/user-guide/administering-the-servers-and-plugins-using-an-api.md create mode 100644 docs/user-guide/app-plugin-configuration.md create mode 100644 docs/user-guide/configuration-directories.md create mode 100644 docs/user-guide/configuration-file.md create mode 100644 docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md create mode 100644 docs/user-guide/controlling-access-to-apps.md create mode 100644 docs/user-guide/controlling-access-to-dataservices.md create mode 100644 docs/user-guide/customizing-security-plugins.md create mode 100644 docs/user-guide/logging-configuration.md create mode 100644 docs/user-guide/managing-cluster-mode-for-app-server.md create mode 100644 docs/user-guide/network-configuration.md create mode 100644 docs/user-guide/setting-up-terminal-app-plugins.md create mode 100644 docs/user-guide/using-multiple-zis-instances.md create mode 100644 docs/user-guide/zss-configuration-1.md diff --git a/docs/user-guide/accessing-zss.md b/docs/user-guide/accessing-zss.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md b/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/user-guide/app-plugin-configuration.md b/docs/user-guide/app-plugin-configuration.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/user-guide/configuration-directories.md b/docs/user-guide/configuration-directories.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/user-guide/configuration-file.md b/docs/user-guide/configuration-file.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md b/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/user-guide/controlling-access-to-apps.md b/docs/user-guide/controlling-access-to-apps.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/user-guide/controlling-access-to-dataservices.md b/docs/user-guide/controlling-access-to-dataservices.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/user-guide/customizing-security-plugins.md b/docs/user-guide/customizing-security-plugins.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/user-guide/logging-configuration.md b/docs/user-guide/logging-configuration.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/user-guide/managing-cluster-mode-for-app-server.md b/docs/user-guide/managing-cluster-mode-for-app-server.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index ba98a63f70..56fcc40433 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -5,498 +5,3 @@ The Zowe Application ("App") Framework is configured in the Zowe configuration f When you install Zowe™, the App Framework is configured as an API 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. You can modify the Zowe App Server and Zowe System Services (ZSS) configuration, as needed, or configure connections for the Terminal app plugins. - -## Accessing ZSS - -The `zss` server should be accessed through the `gateway` when both are present. When both are ready, ZSS can be accessed from the API Mediation Layer Gateway, such as - -`https://:/zss/api/v1/`. - -Although you access the ZSS server via the Gateway port, the ZSS server still needs a port assigned to it which is the value of the *components.zss.port* variable in the Zowe configuration file. - -If the mediation layer is not used, ZSS directly at `https://:/`. - -## 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-app-server/blob/v3.x/staging/schemas/app-server-config.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. - - -## 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, 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 - -Follow these optional steps to configure the default connection to open for the terminal app plugins. - -### Setting up the TN3270 mainframe terminal app plugin - -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": - "security": { - type: <"telnet" or "tls"> - } -``` - -### Setting up the VT Terminal app plugin - -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": - "security": { - type: <"telnet" or "ssh"> - } -``` - -## Network configuration - -**Note:** The following attributes are to be defined in the Zowe configuration file. - -The App Server and ZSS both can be accessed over HTTPS, either natively or via AT-TLS by setting appropriate AT-TLS rules and Zowe YAML assignments. When using native HTTPS, the TLS properties can be further customized within the YAML. - -### Port configuration - -The Zowe YAML property `components..port` can be used to set the port for any Zowe server. By default, the following is used but can be overridden: - -```yaml -components: - app-server: - port: 7556 - zss: - port: 7557 -``` - -### IP configuration - -By default, all Zowe servers listen on the IP address `0.0.0.0`. This can be customized. -The Zowe YAML property `zowe.network.server.tls.listenAddresses` can be used to instruct both `app-server` and `zss` of which IP to listen on. This property can be nested within each component if it is desired to customize them individually. Alternatively, TCPIP port rules can be used to control the assignment of `0.0.0.0` into a particular alternative IP address. -[You can read more about this in the network requirements page](./address-network-requirements.md). - -### Native TLS - -Both `app-server` and `zss` server components default to using HTTPS without the need for AT-TLS. AT-TLS is also possible. When using the native TLS, attributes such as TLS version and ciphers can be customized within the `zowe.network.server.tls` and `zowe.network.client.tls` objects of the Zowe configuration. These objects can also be placed within the `components.zss` and `components.app-server` objects, such as `components.zss.zowe.network.server.tls` in order to individually customize each server TLS configuration. For more information, read [TLS configuration](./tls-configuration.md). - - -### AT-TLS - -You can instruct Zowe servers to expect TLS using the property `zowe.network.server.tls.attls: true`. Use this property is to set AT-TLS for all Zowe servers. For more granular control, you can set the following section in the yaml file: - -```yaml -components: - app-server: - zowe: - network: - server: - tls: - attls: true - client: - tls: - attls: true -``` - -This configuration instructs only the `app-server` component to expect AT-TLS for both inbound and outbound traffic. Similarly, set the parameter `zowe.network.server.tls.attls` to `true` for the `zss` component. Use `zowe.network.server.tls.attls: true` to instruct both servers to expect AT-TLS altogether. For more information, see [Configuring AT-TLS for Zowe server](./configuring-at-tls-for-zowe-server.md). - -#### AT-TLS Rule Suggestions - -The `app-server` and `zss` components of Zowe are servers that may accept incoming connections from each other, other Zowe servers, and clients outside z/OS such as browsers either directly or indirectly such as when API ML is used. - -As such, both Inbound and Outbound direction AT-TLS rules are needed for these servers. -The Inbound rules can be filtered by the listening ports of the servers, but Outbound rules may need to be set by either jobnames or destination ports. - -The ports and jobnames can be found in the [Addressing network requirements](./address-network-requirements.md) documentation. - -The Outbound rules can have HandshakeRole of Client, but when API ML is enabled, it is required that `app-server` and `zss` include their server certificates as client certificates using the `CertificateLabel` property of a `TTLSConnectionAdvancedParms` rule. For more information, see [Configuring AT-TLS for Zowe server](./configuring-at-tls-for-zowe-server.md#outbound-rule-for-communication-between-api-gateway-and-southbound-services). - -The Inbound rules can have a HandshakeRole of Server or ServerWithClientAuth. - - - -### Native TLS - -The configuration object `zowe.network.server.tls` and `zowe.network.client.tls` can be set to control all Zowe components, or just `app-server` or `zss` but nesting the object within them. This object can control ciphers by listing IANA cipher names, minimum and maximum TLS levels, and for some servers even curves can be customized via a list. - -An example for configuration is given below, but the specification for all options is found [within the Zowe YAML schema](https://github.com/zowe/zowe-install-packaging/blob/fdcdb2618080cf87031c070aed7e90503699ab5f/schemas/zowe-yaml-schema.json#L939) - -```yaml -zowe: - network: - server: - tls: # This sets all servers to default only to use TLSv1.3, with only specific ciphers - minTls: "TLSv1.3" - maxTls: "TLSv1.3" - ciphers: - - "TLS_AES_128_GCM_SHA256" - - "TLS_AES_256_GCM_SHA384" -components: - app-server: - zowe: - network: - client: - tls: # This customizes the app-server specifically to have a different minimum TLS for client requests - minTls: "TLSv1.2" -``` - - -## Configuration Directories -When running, the App Server will access the server's settings and read or modify the contents of its resource storage. All of this data is stored within a hierarchy of folders which correspond to scopes: - -- Product: The contents of this folder are not meant to be modified, but used as defaults for a product. -- Site: The contents of this folder are intended to be shared across multiple App Server instances, perhaps on a network drive. -- Instance: This folder represents the broadest scope of data within the given App Server instance. -- 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/extend-desktop/mvd-configdataservice.md) - - -## App plugin configuration - -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 - -ZSS provides APIs that any server or client can use. By default, the Zowe Desktop includes Apps which rely upon ZSS APIs, and therefore it's recommended that whenever the `app-server` is enabled in the Zowe YAML, that `zss` is also enabled. - - -### ZSS 64 or 31 bit modes - -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. - -#### Verifying which ZSS mode is in use - -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: - -`ZWES1013I ZSS Server has started. Version 3.0.0 64-bit` - -Or - -`ZWES1013I ZSS Server has started. Version 3.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. - -#### Customizing ZSS session duration - -In a standard Zowe installation, all Zowe servers utilize the API Mediation Layer's token-based, single-sign on authentication. This authentication in turn cooperates with z/OSMF, and the session duration is typically that of z/OSMF's, which defaults to 8 hours before the session expires. In that situation, customization of session duration is best done by customizing z/OSMF's session duration, as a part of its Liberty configuration. - -If you are not using the API Mediation Layer, or are trying to contact ZSS directly, then ZSS's own session logic is used. When authenticated directly to ZSS, it will respond to authenticated HTTP requests with a cookie which is valid by default for 1 hour. This can be customized by creating and editing a file named "timeouts.json" within ZSS's instance directory. The default location is `/app-server/serverConfig/timeouts.json`, because the default instance directory is `/app-server`, but can be customized by editing the value of `components.zss.instanceDir`. - -The timeouts.json file has the following layout: - -``` -{ - "users": { - "zoweuser1": 3600 - }, - "groups": { - "developers": 7200 - } -} -``` - -Where you can have a "users" section that lists user accounts on the z/OS system, and "groups" section that lists groups on that system. -The numbers for each entry are in seconds, where in the example `zoweuser1` has the default session duration value of 1 hour. -It is possible that a user specified in this file is also in a group specified in this file. If so, the user value takes priority. -If a user authenticates to ZSS and their user or group is not found in this file, then the default value of 1 hour is used. -If this file is missing, Zowe will print a message about it missing, but it does not harm Zowe as the default value of 1 hour would be used for all direct authentications to 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. - -The following steps can be followed to point a Zowe instance at a particular ZIS server. - -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. - -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 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. - -4. [Stop the Zowe instance you wish to point to the ZIS server](../user-guide/start-zowe-zos.md). - -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. [Restart the Zowe instance](../user-guide/start-zowe-zos.md#starting-and-stopping-zowe-main-server-zweslstc-on-zos-with-zwe-server-command) - -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)` - - -## Controlling access to apps - -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. - -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. - -### Enabling RBAC - -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* and *components.app-server.dataserviceAuthentication.rbac* variables to `true` in the Zowe configuration file. - -### Controlling app access for all users - -**Note:** -- `` variable comes from the Zowe configuration file. - -1. Enable RBAC. - -2. Navigate to the following location: - ``` - /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: - ``` - /app-server/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins - ``` -4. Open the copied `allowedPlugins.json` file and perform either of the following steps: - - 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](start-zowe-zos.md). - -### 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: - ``` - /app-server/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: - ``` - /components/app-server/share/zlux-app-server/defaults/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins - ``` -6. Open the `allowedPlugins.json` file and specify apps that user can access. For example: - ```json - { - "allowedPlugins": [ - { - "identifier": "org.zowe.appA", - "versions": [ - "1.1" - ] - }, - { - "identifier": "org.zowe.appB", - "versions": [ - "*" - ] - }, - } - ``` - - **Notes:** - - Identifier and version attributes are required. - - When a user logs in to the desktop, Zowe determines which apps they can see by concatenating the list of apps available to all users with the apps available to the individual user. - -6. [Restart the app server](start-zowe-zos.md). - - -## 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 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. - -### 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. - -Endpoints are identified by URIs in the following format: - -`/ZLUX/plugins//services///` - -For example: - -`/ZLUX/plugins/org.zowe.foo/services/baz/_current/users/fred` - -Where the path is `/users/fred`. - -SAF profiles have the following format: - -`ZLUX......` - -For example, to issue a POST request to the dataservice endpoint documented above, users must have READ access to the following profile: - -`ZLUX.1.SVC.ORG_ZOWE_FOO.BAZ.POST.USERS.FRED` - -For configuration dataservice endpoint profiles use the service code `CFG`. For core dataservice endpoints use `COR`. For all other dataservice endpoints use `SVC`. - -### Creating generic authorization profiles -Some endpoints can generate an unlimited number of URIs. For example, an endpoint that performs a DELETE action on any file would generate a different URI for each file, and users can create an unlimited number of files. To apply RBAC to this type of endpoint you must create a generic profile, for example: - -`ZLUX.1.COR.ORG_ZOWE_FOO.BAZ.DELETE.**` - -You can create generic profile names using wildcards, such as asterisks (*). For information on generic profile naming, see [IBM documentation](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.icha100/egnoff.htm). - -### Configuring basic authorization - -The following are recommended for basic authorization: - -- To give administrators access to everything in Zowe, create the following profile and give them UPDATE access to it: `ZLUX.**` -- To give non-administrators basic access to the site and product, create the following profile and give them READ access to it: `ZLUX.*.ORG_ZOWE_*` -- To prevent non-administrators from configuring endpoints at the product and instance levels, create the following profile and do not give them access to it: `ZLUX.1.CFG.**` -- To give non-administrators all access to user, create the following profile and give them UPDATE access to it: `ZLUX.1.CFG.*.*.USER.**` - - -### Endpoint URL length limitations -SAF profiles cannot contain more than 246 characters. If the path section of an endpoint URL is long enough that the profile name exceeds the limit, the path is trimmed to only include elements that do not exceed the limit. To avoid this issue, we recommend that appliction developers maintain relatively short endpoint URL paths. - -For information on endpoint URLs, see [Using dataservices with RBAC](../extend/extend-desktop/mvd-dataservices.md#using-dataservices-with-rbac) - -## Customizing Security Plugins - -By default, the `app-server` handles security questions by utilizing either the API Mediation Layer, or ZSS, depending on which is present. If the API Mediation Layer is present, it is used to establish an SSO session which ZSS also respects. When RBAC is enabled, ZSS is queried for authorization questions. - -This behavior is performed by an `app-server` security plugin named `sso-auth`. -Security plugins can be installed as part of Zowe extensions, and `app-server` can be customized to prefer them via the Zowe YAML. -Different security plugins could be used to operate in different environments, with different security systems, or with different session characteristics. -For more information, [read the extender's guide on security plugins](../extend/extend-desktop/mvd-authentication-api.md) - -### Session duration and expiration - -After successful authentication, a Zowe Desktop session is created by authentication plugins. - -The duration of the session is determined by the plugin used. Some plugins are capable of renewing the session prior to expiration, while others may have a fixed session length. - -The session duration and expiration behavior of the default security plugin, `sso-auth`, is determined by API Medation Layer configuration if present, and otherwise upon ZSS configuration. -If API Medation Layer is enabled, by default it will use z/OSMF as the session provider and the session duration will be based upon z/OSMF settings. [You can read more about API Mediation Layer providers here](authentication-providers-for-apiml.md). -If the API Mediation Layer is not enabled, you can [use or customize ZSS's default session duration of one hour](#customizing-zss-session-duration). - -When a session expires, the credentials used for the initial login are likely to be invalid for re-use, since MFA credentials are often one-time-use or time-based. - -In the Desktop, Apps that you opened prior to expiration will remain open so that your work can resume after entering new credentials. - - -## Administering the servers and plugins using an API -The App Server has a REST API to retrieve and edit both the App Server and ZSS server configuration values, and list, add, update, and delete plugins. Most of the features require RBAC to be enabled and for your user to have RBAC access to utilize these endpoints. For more information see documentation on how to [use RBAC](https://docs.zowe.org/stable/user-guide/mvd-configuration.html#controlling-access-to-dataservices) - -The API returns the following information in a JSON response: - -| API | Description | -| --------------------------------------------------------- | ------------------------------------------------------------ | -| /server (GET) | Returns a list of accessible server endpoints for the Zowe App Server. | -| /server/config (GET) | Returns the Zowe App Server configuration which follows [this specification](https://github.com/zowe/zlux-app-server/blob/v3.x/master/schemas/app-server-config.json). | -| /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 which follows [this specification](https://github.com/zowe/zss/blob/v3.x/staging/schemas/zss-config.json). | -| /server/agent/log (GET) | Returns the contents of the ZSS log file. | -| /server/agent/loglevels (GET) | Returns the verbosity levels of the ZSS logger. | -| /server/agent/environment (GET) | Returns ZSS environment information. | -| /server/logLevels/name/:componentName/level/:level (POST) | Specify the logger that you are using and a verbosity level. | -| /plugins (GET) | Returns a list of all plugins and their dataservices. | -| /plugins (PUT) | Adds a new plugin or upgrades an existing plugin. Only available in cluster mode (default). | -| /plugins/:id (DELETE) | Deletes a plugin. Only available in cluster mode (default). | - -Swagger API documentation is provided in the `/components/app-server/share/zlux-app-server/doc/swagger/server-plugins-api.yaml` file. To see it in HTML format, you can paste the contents into the Swagger editor at https://editor.swagger.io/. - -**Note:** The "agent" end points interact with the agent specified in the zowe configuration file. By default this is ZSS. - - -## Managing Cluster Mode for app-server - -On the Zowe servers, the component "app-server" has an environment variable "ZLUX_NO_CLUSTER" which controls whether or not it uses cluster mode. Cluster mode is enabled by default. However, you might need to disable cluster mode under certain circumstances. When cluster mode is disabled, make sure you are aware of the potential drawbacks and benefit. - -When you **disable** cluster mode, you will lose the following benefits: - -1. **Performance under high user Count:** This is due to the absence of redundant workers, which can impact the system's efficiency when dealing with a large number of users. - -2. **Reduced downtime during unexpected exceptions:** The low-downtime characteristic, where only one request is interrupted compared to around 15 seconds of downtime, is compromised. - -### To turn the cluster mode on - -- Do NOT include the `zowe.environments.ZLUX_NO_CLUSTER `in the `zowe.yaml` file. - -### To turn the cluster mode off - -- Include `zowe.environments.ZLUX_NO_CLUSTER=1` in the `zowe.yaml` file. - diff --git a/docs/user-guide/network-configuration.md b/docs/user-guide/network-configuration.md new file mode 100644 index 0000000000..ca34a71740 --- /dev/null +++ b/docs/user-guide/network-configuration.md @@ -0,0 +1,89 @@ +## Network configuration + +**Note:** The following attributes are to be defined in the Zowe configuration file. + +The App Server and ZSS both can be accessed over HTTPS, either natively or via AT-TLS by setting appropriate AT-TLS rules and Zowe YAML assignments. When using native HTTPS, the TLS properties can be further customized within the YAML. + +### Port configuration + +The Zowe YAML property `components..port` can be used to set the port for any Zowe server. By default, the following is used but can be overridden: + +```yaml +components: + app-server: + port: 7556 + zss: + port: 7557 +``` + +### IP configuration + +By default, all Zowe servers listen on the IP address `0.0.0.0`. This can be customized. +The Zowe YAML property `zowe.network.server.tls.listenAddresses` can be used to instruct both `app-server` and `zss` of which IP to listen on. This property can be nested within each component if it is desired to customize them individually. Alternatively, TCPIP port rules can be used to control the assignment of `0.0.0.0` into a particular alternative IP address. +[You can read more about this in the network requirements page](./address-network-requirements.md). + +### Native TLS + +Both `app-server` and `zss` server components default to using HTTPS without the need for AT-TLS. AT-TLS is also possible. When using the native TLS, attributes such as TLS version and ciphers can be customized within the `zowe.network.server.tls` and `zowe.network.client.tls` objects of the Zowe configuration. These objects can also be placed within the `components.zss` and `components.app-server` objects, such as `components.zss.zowe.network.server.tls` in order to individually customize each server TLS configuration. For more information, read [TLS configuration](./tls-configuration.md). + + +### AT-TLS + +You can instruct Zowe servers to expect TLS using the property `zowe.network.server.tls.attls: true`. Use this property is to set AT-TLS for all Zowe servers. For more granular control, you can set the following section in the yaml file: + +```yaml +components: + app-server: + zowe: + network: + server: + tls: + attls: true + client: + tls: + attls: true +``` + +This configuration instructs only the `app-server` component to expect AT-TLS for both inbound and outbound traffic. Similarly, set the parameter `zowe.network.server.tls.attls` to `true` for the `zss` component. Use `zowe.network.server.tls.attls: true` to instruct both servers to expect AT-TLS altogether. For more information, see [Configuring AT-TLS for Zowe server](./configuring-at-tls-for-zowe-server.md). + +#### AT-TLS Rule Suggestions + +The `app-server` and `zss` components of Zowe are servers that may accept incoming connections from each other, other Zowe servers, and clients outside z/OS such as browsers either directly or indirectly such as when API ML is used. + +As such, both Inbound and Outbound direction AT-TLS rules are needed for these servers. +The Inbound rules can be filtered by the listening ports of the servers, but Outbound rules may need to be set by either jobnames or destination ports. + +The ports and jobnames can be found in the [Addressing network requirements](./address-network-requirements.md) documentation. + +The Outbound rules can have HandshakeRole of Client, but when API ML is enabled, it is required that `app-server` and `zss` include their server certificates as client certificates using the `CertificateLabel` property of a `TTLSConnectionAdvancedParms` rule. For more information, see [Configuring AT-TLS for Zowe server](./configuring-at-tls-for-zowe-server.md#outbound-rule-for-communication-between-api-gateway-and-southbound-services). + +The Inbound rules can have a HandshakeRole of Server or ServerWithClientAuth. + + + +### Native TLS + +The configuration object `zowe.network.server.tls` and `zowe.network.client.tls` can be set to control all Zowe components, or just `app-server` or `zss` but nesting the object within them. This object can control ciphers by listing IANA cipher names, minimum and maximum TLS levels, and for some servers even curves can be customized via a list. + +An example for configuration is given below, but the specification for all options is found [within the Zowe YAML schema](https://github.com/zowe/zowe-install-packaging/blob/fdcdb2618080cf87031c070aed7e90503699ab5f/schemas/zowe-yaml-schema.json#L939) + +```yaml +zowe: + network: + server: + tls: # This sets all servers to default only to use TLSv1.3, with only specific ciphers + minTls: "TLSv1.3" + maxTls: "TLSv1.3" + ciphers: + - "TLS_AES_128_GCM_SHA256" + - "TLS_AES_256_GCM_SHA384" +components: + app-server: + zowe: + network: + client: + tls: # This customizes the app-server specifically to have a different minimum TLS for client requests + minTls: "TLSv1.2" +``` + + diff --git a/docs/user-guide/setting-up-terminal-app-plugins.md b/docs/user-guide/setting-up-terminal-app-plugins.md new file mode 100644 index 0000000000..db4adeea64 --- /dev/null +++ b/docs/user-guide/setting-up-terminal-app-plugins.md @@ -0,0 +1,28 @@ +## 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 + +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": + "security": { + type: <"telnet" or "tls"> + } +``` + +### Setting up the VT Terminal app plugin + +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": + "security": { + type: <"telnet" or "ssh"> + } +``` + diff --git a/docs/user-guide/using-multiple-zis-instances.md b/docs/user-guide/using-multiple-zis-instances.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/user-guide/zss-configuration-1.md b/docs/user-guide/zss-configuration-1.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/sidebars.js b/sidebars.js index 42b9d958c3..e34fd4931b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -339,8 +339,29 @@ module.exports = { "user-guide/configmgr-using", "user-guide/install-configure-zos-extensions", "user-guide/mvd-configuration", + { + type: "category", + label: "Advanced Application Framework Configuration", link: { type: "doc", id: "user-guide/mvd-configuration", }, + collapsed: false, + items: ["user-guide/accessing-zss", + "user-guide/configuration-file", + "user-guide/configuring-the-framework-as-a-mediation-layer-client", + "user-guide/setting-up-terminal-app-plugins", + "user-guide/network-configuration", + "user-guide/configuration-directories", + "user-guide/app-plugin-configuration", + "user-guide/logging-configuration", + "user-guide/zss-configuration-1", + "user-guide/using-multiple-zis-instances", + "user-guide/controlling-access-to-apps", + "user-guide/controlling-access-to-dataservices", + "user-guide/customizing-security-plugins", + "user-guide/administering-the-servers-and-plugins-using-an-api", + "user-guide/managing-cluster-mode-for-app-server", + ], + }, ], - } + }, ], }, { From 2cab9c54d2ff218d9b6899d221d6fcf051c30736 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Mon, 17 Nov 2025 22:33:34 +0530 Subject: [PATCH 02/57] Dividing mvd-configuration.md Signed-off-by: arooshlele --- ...ng-the-servers-and-plugins-using-an-api.md | 28 +++++++++++++++++++ .../customizing-security-plugins.md | 24 ++++++++++++++++ .../managing-cluster-mode-for-app-server.md | 18 ++++++++++++ 3 files changed, 70 insertions(+) diff --git a/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md b/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md index e69de29bb2..1649b55075 100644 --- a/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md +++ b/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md @@ -0,0 +1,28 @@ +## Administering the servers and plugins using an API +The App Server has a REST API to retrieve and edit both the App Server and ZSS server configuration values, and list, add, update, and delete plugins. Most of the features require RBAC to be enabled and for your user to have RBAC access to utilize these endpoints. For more information see documentation on how to [use RBAC](https://docs.zowe.org/stable/user-guide/mvd-configuration.html#controlling-access-to-dataservices) + +The API returns the following information in a JSON response: + +| API | Description | +| --------------------------------------------------------- | ------------------------------------------------------------ | +| /server (GET) | Returns a list of accessible server endpoints for the Zowe App Server. | +| /server/config (GET) | Returns the Zowe App Server configuration which follows [this specification](https://github.com/zowe/zlux-app-server/blob/v3.x/master/schemas/app-server-config.json). | +| /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 which follows [this specification](https://github.com/zowe/zss/blob/v3.x/staging/schemas/zss-config.json). | +| /server/agent/log (GET) | Returns the contents of the ZSS log file. | +| /server/agent/loglevels (GET) | Returns the verbosity levels of the ZSS logger. | +| /server/agent/environment (GET) | Returns ZSS environment information. | +| /server/logLevels/name/:componentName/level/:level (POST) | Specify the logger that you are using and a verbosity level. | +| /plugins (GET) | Returns a list of all plugins and their dataservices. | +| /plugins (PUT) | Adds a new plugin or upgrades an existing plugin. Only available in cluster mode (default). | +| /plugins/:id (DELETE) | Deletes a plugin. Only available in cluster mode (default). | + +Swagger API documentation is provided in the `/components/app-server/share/zlux-app-server/doc/swagger/server-plugins-api.yaml` file. To see it in HTML format, you can paste the contents into the Swagger editor at https://editor.swagger.io/. + +**Note:** The "agent" end points interact with the agent specified in the zowe configuration file. By default this is ZSS. + + diff --git a/docs/user-guide/customizing-security-plugins.md b/docs/user-guide/customizing-security-plugins.md index e69de29bb2..4ce4739775 100644 --- a/docs/user-guide/customizing-security-plugins.md +++ b/docs/user-guide/customizing-security-plugins.md @@ -0,0 +1,24 @@ +## Customizing Security Plugins + +By default, the `app-server` handles security questions by utilizing either the API Mediation Layer, or ZSS, depending on which is present. If the API Mediation Layer is present, it is used to establish an SSO session which ZSS also respects. When RBAC is enabled, ZSS is queried for authorization questions. + +This behavior is performed by an `app-server` security plugin named `sso-auth`. +Security plugins can be installed as part of Zowe extensions, and `app-server` can be customized to prefer them via the Zowe YAML. +Different security plugins could be used to operate in different environments, with different security systems, or with different session characteristics. +For more information, [read the extender's guide on security plugins](../extend/extend-desktop/mvd-authentication-api.md) + +### Session duration and expiration + +After successful authentication, a Zowe Desktop session is created by authentication plugins. + +The duration of the session is determined by the plugin used. Some plugins are capable of renewing the session prior to expiration, while others may have a fixed session length. + +The session duration and expiration behavior of the default security plugin, `sso-auth`, is determined by API Medation Layer configuration if present, and otherwise upon ZSS configuration. +If API Medation Layer is enabled, by default it will use z/OSMF as the session provider and the session duration will be based upon z/OSMF settings. [You can read more about API Mediation Layer providers here](authentication-providers-for-apiml.md). +If the API Mediation Layer is not enabled, you can [use or customize ZSS's default session duration of one hour](#customizing-zss-session-duration). + +When a session expires, the credentials used for the initial login are likely to be invalid for re-use, since MFA credentials are often one-time-use or time-based. + +In the Desktop, Apps that you opened prior to expiration will remain open so that your work can resume after entering new credentials. + + diff --git a/docs/user-guide/managing-cluster-mode-for-app-server.md b/docs/user-guide/managing-cluster-mode-for-app-server.md index e69de29bb2..9cd9282187 100644 --- a/docs/user-guide/managing-cluster-mode-for-app-server.md +++ b/docs/user-guide/managing-cluster-mode-for-app-server.md @@ -0,0 +1,18 @@ +## Managing Cluster Mode for app-server + +On the Zowe servers, the component "app-server" has an environment variable "ZLUX_NO_CLUSTER" which controls whether or not it uses cluster mode. Cluster mode is enabled by default. However, you might need to disable cluster mode under certain circumstances. When cluster mode is disabled, make sure you are aware of the potential drawbacks and benefit. + +When you **disable** cluster mode, you will lose the following benefits: + +1. **Performance under high user Count:** This is due to the absence of redundant workers, which can impact the system's efficiency when dealing with a large number of users. + +2. **Reduced downtime during unexpected exceptions:** The low-downtime characteristic, where only one request is interrupted compared to around 15 seconds of downtime, is compromised. + +### To turn the cluster mode on + +- Do NOT include the `zowe.environments.ZLUX_NO_CLUSTER `in the `zowe.yaml` file. + +### To turn the cluster mode off + +- Include `zowe.environments.ZLUX_NO_CLUSTER=1` in the `zowe.yaml` file. + From d1036ebff5c28e5999e0d3482bf8d269af9b468c Mon Sep 17 00:00:00 2001 From: arooshlele Date: Mon, 17 Nov 2025 22:36:50 +0530 Subject: [PATCH 03/57] Updating administering-the-servers-and-plugins-using-an-api.md Signed-off-by: arooshlele --- .../administering-the-servers-and-plugins-using-an-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md b/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md index 1649b55075..d69e4ae4af 100644 --- a/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md +++ b/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md @@ -1,7 +1,7 @@ ## Administering the servers and plugins using an API The App Server has a REST API to retrieve and edit both the App Server and ZSS server configuration values, and list, add, update, and delete plugins. Most of the features require RBAC to be enabled and for your user to have RBAC access to utilize these endpoints. For more information see documentation on how to [use RBAC](https://docs.zowe.org/stable/user-guide/mvd-configuration.html#controlling-access-to-dataservices) -The API returns the following information in a JSON response: +The API returns the following information in a JSON response: | API | Description | | --------------------------------------------------------- | ------------------------------------------------------------ | From b2ea72ccacd23da97d403986fc650878ffa007b4 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Mon, 17 Nov 2025 22:38:37 +0530 Subject: [PATCH 04/57] Adding files under mvd-configuration.md Signed-off-by: arooshlele --- ...e-framework-as-a-mediation-layer-client.md | 5 ++ .../controlling-access-to-dataservices.md | 50 +++++++++++++++++++ 2 files changed, 55 insertions(+) diff --git a/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md b/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md index e69de29bb2..40081637df 100644 --- a/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md +++ b/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md @@ -0,0 +1,5 @@ +## 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, 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. + diff --git a/docs/user-guide/controlling-access-to-dataservices.md b/docs/user-guide/controlling-access-to-dataservices.md index e69de29bb2..393c8b3eda 100644 --- a/docs/user-guide/controlling-access-to-dataservices.md +++ b/docs/user-guide/controlling-access-to-dataservices.md @@ -0,0 +1,50 @@ +## 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 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. + +### 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. + +Endpoints are identified by URIs in the following format: + +`/ZLUX/plugins//services///` + +For example: + +`/ZLUX/plugins/org.zowe.foo/services/baz/_current/users/fred` + +Where the path is `/users/fred`. + +SAF profiles have the following format: + +`ZLUX......` + +For example, to issue a POST request to the dataservice endpoint documented above, users must have READ access to the following profile: + +`ZLUX.1.SVC.ORG_ZOWE_FOO.BAZ.POST.USERS.FRED` + +For configuration dataservice endpoint profiles use the service code `CFG`. For core dataservice endpoints use `COR`. For all other dataservice endpoints use `SVC`. + +### Creating generic authorization profiles +Some endpoints can generate an unlimited number of URIs. For example, an endpoint that performs a DELETE action on any file would generate a different URI for each file, and users can create an unlimited number of files. To apply RBAC to this type of endpoint you must create a generic profile, for example: + +`ZLUX.1.COR.ORG_ZOWE_FOO.BAZ.DELETE.**` + +You can create generic profile names using wildcards, such as asterisks (*). For information on generic profile naming, see [IBM documentation](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.icha100/egnoff.htm). + +### Configuring basic authorization + +The following are recommended for basic authorization: + +- To give administrators access to everything in Zowe, create the following profile and give them UPDATE access to it: `ZLUX.**` +- To give non-administrators basic access to the site and product, create the following profile and give them READ access to it: `ZLUX.*.ORG_ZOWE_*` +- To prevent non-administrators from configuring endpoints at the product and instance levels, create the following profile and do not give them access to it: `ZLUX.1.CFG.**` +- To give non-administrators all access to user, create the following profile and give them UPDATE access to it: `ZLUX.1.CFG.*.*.USER.**` + + +### Endpoint URL length limitations +SAF profiles cannot contain more than 246 characters. If the path section of an endpoint URL is long enough that the profile name exceeds the limit, the path is trimmed to only include elements that do not exceed the limit. To avoid this issue, we recommend that appliction developers maintain relatively short endpoint URL paths. + +For information on endpoint URLs, see [Using dataservices with RBAC](../extend/extend-desktop/mvd-dataservices.md#using-dataservices-with-rbac) + From 227ab0358133865d8d020c38a378ed297dfe9261 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Mon, 17 Nov 2025 22:39:58 +0530 Subject: [PATCH 05/57] Adding files under mvd-configuration.md Signed-off-by: arooshlele --- docs/user-guide/accessing-zss.md | 10 +++ docs/user-guide/configuration-file.md | 11 +++ docs/user-guide/controlling-access-to-apps.md | 74 +++++++++++++++++++ .../using-multiple-zis-instances.md | 28 +++++++ 4 files changed, 123 insertions(+) diff --git a/docs/user-guide/accessing-zss.md b/docs/user-guide/accessing-zss.md index e69de29bb2..f688c4c94a 100644 --- a/docs/user-guide/accessing-zss.md +++ b/docs/user-guide/accessing-zss.md @@ -0,0 +1,10 @@ +## Accessing ZSS + +The `zss` server should be accessed through the `gateway` when both are present. When both are ready, ZSS can be accessed from the API Mediation Layer Gateway, such as + +`https://:/zss/api/v1/`. + +Although you access the ZSS server via the Gateway port, the ZSS server still needs a port assigned to it which is the value of the *components.zss.port* variable in the Zowe configuration file. + +If the mediation layer is not used, ZSS directly at `https://:/`. + diff --git a/docs/user-guide/configuration-file.md b/docs/user-guide/configuration-file.md index e69de29bb2..f169e54a5e 100644 --- a/docs/user-guide/configuration-file.md +++ b/docs/user-guide/configuration-file.md @@ -0,0 +1,11 @@ +## 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-app-server/blob/v3.x/staging/schemas/app-server-config.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. + + diff --git a/docs/user-guide/controlling-access-to-apps.md b/docs/user-guide/controlling-access-to-apps.md index e69de29bb2..f307493bad 100644 --- a/docs/user-guide/controlling-access-to-apps.md +++ b/docs/user-guide/controlling-access-to-apps.md @@ -0,0 +1,74 @@ +## Controlling access to apps + +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. + +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. + +### Enabling RBAC + +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* and *components.app-server.dataserviceAuthentication.rbac* variables to `true` in the Zowe configuration file. + +### Controlling app access for all users + +**Note:** +- `` variable comes from the Zowe configuration file. + +1. Enable RBAC. + +2. Navigate to the following location: + ``` + /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: + ``` + /app-server/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins + ``` +4. Open the copied `allowedPlugins.json` file and perform either of the following steps: + - 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](start-zowe-zos.md). + +### 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: + ``` + /app-server/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: + ``` + /components/app-server/share/zlux-app-server/defaults/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins + ``` +6. Open the `allowedPlugins.json` file and specify apps that user can access. For example: + ```json + { + "allowedPlugins": [ + { + "identifier": "org.zowe.appA", + "versions": [ + "1.1" + ] + }, + { + "identifier": "org.zowe.appB", + "versions": [ + "*" + ] + }, + } + ``` + + **Notes:** + - Identifier and version attributes are required. + - When a user logs in to the desktop, Zowe determines which apps they can see by concatenating the list of apps available to all users with the apps available to the individual user. + +6. [Restart the app server](start-zowe-zos.md). + + diff --git a/docs/user-guide/using-multiple-zis-instances.md b/docs/user-guide/using-multiple-zis-instances.md index e69de29bb2..b93707d98d 100644 --- a/docs/user-guide/using-multiple-zis-instances.md +++ b/docs/user-guide/using-multiple-zis-instances.md @@ -0,0 +1,28 @@ +## 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. + +The following steps can be followed to point a Zowe instance at a particular ZIS server. + +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. + +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 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. + +4. [Stop the Zowe instance you wish to point to the ZIS server](../user-guide/start-zowe-zos.md). + +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. [Restart the Zowe instance](../user-guide/start-zowe-zos.md#starting-and-stopping-zowe-main-server-zweslstc-on-zos-with-zwe-server-command) + +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 41e99cd6a114367a9c075d376314ae1e0045722d Mon Sep 17 00:00:00 2001 From: arooshlele Date: Mon, 17 Nov 2025 22:41:56 +0530 Subject: [PATCH 06/57] Adding files under mvd-configuration.md Signed-off-by: arooshlele --- docs/user-guide/app-plugin-configuration.md | 4 ++ docs/user-guide/configuration-file.md | 2 +- docs/user-guide/logging-configuration.md | 54 +++++++++++++++++++ docs/user-guide/zss-configuration-1.md | 59 +++++++++++++++++++++ 4 files changed, 118 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/app-plugin-configuration.md b/docs/user-guide/app-plugin-configuration.md index e69de29bb2..99b7470079 100644 --- a/docs/user-guide/app-plugin-configuration.md +++ b/docs/user-guide/app-plugin-configuration.md @@ -0,0 +1,4 @@ +## App plugin configuration + +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. + diff --git a/docs/user-guide/configuration-file.md b/docs/user-guide/configuration-file.md index f169e54a5e..d842ac539e 100644 --- a/docs/user-guide/configuration-file.md +++ b/docs/user-guide/configuration-file.md @@ -6,6 +6,6 @@ The app-server uses the Zowe server configuration file for customizing server be ### 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. +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. diff --git a/docs/user-guide/logging-configuration.md b/docs/user-guide/logging-configuration.md index e69de29bb2..8a2fb4c68d 100644 --- a/docs/user-guide/logging-configuration.md +++ b/docs/user-guide/logging-configuration.md @@ -0,0 +1,54 @@ +## 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). + + diff --git a/docs/user-guide/zss-configuration-1.md b/docs/user-guide/zss-configuration-1.md index e69de29bb2..513e0dd8f4 100644 --- a/docs/user-guide/zss-configuration-1.md +++ b/docs/user-guide/zss-configuration-1.md @@ -0,0 +1,59 @@ +## ZSS configuration + +ZSS provides APIs that any server or client can use. By default, the Zowe Desktop includes Apps which rely upon ZSS APIs, and therefore it's recommended that whenever the `app-server` is enabled in the Zowe YAML, that `zss` is also enabled. + + +### ZSS 64 or 31 bit modes + +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. + +#### Verifying which ZSS mode is in use + +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: + +`ZWES1013I ZSS Server has started. Version 3.0.0 64-bit` + +Or + +`ZWES1013I ZSS Server has started. Version 3.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. + +#### Customizing ZSS session duration + +In a standard Zowe installation, all Zowe servers utilize the API Mediation Layer's token-based, single-sign on authentication. This authentication in turn cooperates with z/OSMF, and the session duration is typically that of z/OSMF's, which defaults to 8 hours before the session expires. In that situation, customization of session duration is best done by customizing z/OSMF's session duration, as a part of its Liberty configuration. + +If you are not using the API Mediation Layer, or are trying to contact ZSS directly, then ZSS's own session logic is used. When authenticated directly to ZSS, it will respond to authenticated HTTP requests with a cookie which is valid by default for 1 hour. This can be customized by creating and editing a file named "timeouts.json" within ZSS's instance directory. The default location is `/app-server/serverConfig/timeouts.json`, because the default instance directory is `/app-server`, but can be customized by editing the value of `components.zss.instanceDir`. + +The timeouts.json file has the following layout: + +``` +{ + "users": { + "zoweuser1": 3600 + }, + "groups": { + "developers": 7200 + } +} +``` + +Where you can have a "users" section that lists user accounts on the z/OS system, and "groups" section that lists groups on that system. +The numbers for each entry are in seconds, where in the example `zoweuser1` has the default session duration value of 1 hour. +It is possible that a user specified in this file is also in a group specified in this file. If so, the user value takes priority. +If a user authenticates to ZSS and their user or group is not found in this file, then the default value of 1 hour is used. +If this file is missing, Zowe will print a message about it missing, but it does not harm Zowe as the default value of 1 hour would be used for all direct authentications to ZSS. + + From 5575ca0de4b7321ab90b45fa2c79be826dbf272f Mon Sep 17 00:00:00 2001 From: arooshlele Date: Mon, 17 Nov 2025 22:43:25 +0530 Subject: [PATCH 07/57] Adding files under mvd-configuration.md Signed-off-by: arooshlele --- docs/user-guide/configuration-directories.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/user-guide/configuration-directories.md b/docs/user-guide/configuration-directories.md index e69de29bb2..0ed4f7abce 100644 --- a/docs/user-guide/configuration-directories.md +++ b/docs/user-guide/configuration-directories.md @@ -0,0 +1,12 @@ +## Configuration Directories +When running, the App Server will access the server's settings and read or modify the contents of its resource storage. All of this data is stored within a hierarchy of folders which correspond to scopes: + +- Product: The contents of this folder are not meant to be modified, but used as defaults for a product. +- Site: The contents of this folder are intended to be shared across multiple App Server instances, perhaps on a network drive. +- Instance: This folder represents the broadest scope of data within the given App Server instance. +- 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/extend-desktop/mvd-configdataservice.md) + + From 529999c008335f4b23d32b12ca50f5395cd76f0d Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 10:24:51 +0530 Subject: [PATCH 08/57] Updating accessing-zss.md Signed-off-by: arooshlele --- docs/user-guide/accessing-zss.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/accessing-zss.md b/docs/user-guide/accessing-zss.md index f688c4c94a..421eb64964 100644 --- a/docs/user-guide/accessing-zss.md +++ b/docs/user-guide/accessing-zss.md @@ -1,4 +1,4 @@ -## Accessing ZSS +# Accessing ZSS The `zss` server should be accessed through the `gateway` when both are present. When both are ready, ZSS can be accessed from the API Mediation Layer Gateway, such as From ee41299fd08f4eb6cbc417d548ffe932fdd8f0bf Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 11:09:08 +0530 Subject: [PATCH 09/57] Updating configuration-file.md, configuring-the-framework-as-a-mediation-layer-client.md, setting-up-terminal-app-plugins.md Signed-off-by: arooshlele --- docs/user-guide/configuration-file.md | 2 +- .../configuring-the-framework-as-a-mediation-layer-client.md | 2 +- docs/user-guide/setting-up-terminal-app-plugins.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/configuration-file.md b/docs/user-guide/configuration-file.md index d842ac539e..a2227946fc 100644 --- a/docs/user-guide/configuration-file.md +++ b/docs/user-guide/configuration-file.md @@ -1,4 +1,4 @@ -## Configuration file +# Configuration file ### app-server configuration diff --git a/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md b/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md index 40081637df..57f2b6597d 100644 --- a/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md +++ b/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md @@ -1,4 +1,4 @@ -## Configuring the framework as a Mediation Layer client +# 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, 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. diff --git a/docs/user-guide/setting-up-terminal-app-plugins.md b/docs/user-guide/setting-up-terminal-app-plugins.md index db4adeea64..6a09e10a9f 100644 --- a/docs/user-guide/setting-up-terminal-app-plugins.md +++ b/docs/user-guide/setting-up-terminal-app-plugins.md @@ -1,4 +1,4 @@ -## Setting up terminal app plugins +# Setting up terminal app plugins Follow these optional steps to configure the default connection to open for the terminal app plugins. From 3cd73744ca1f7575d66a011eee5e84d9580f41c3 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 11:14:10 +0530 Subject: [PATCH 10/57] Updating network-configuration.md, configuration-directories.md, app-plugin-configuration.md, logging-configuration.md Signed-off-by: arooshlele --- docs/user-guide/app-plugin-configuration.md | 2 +- docs/user-guide/configuration-directories.md | 2 +- docs/user-guide/logging-configuration.md | 2 +- docs/user-guide/network-configuration.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/app-plugin-configuration.md b/docs/user-guide/app-plugin-configuration.md index 99b7470079..77e7f0a5ac 100644 --- a/docs/user-guide/app-plugin-configuration.md +++ b/docs/user-guide/app-plugin-configuration.md @@ -1,4 +1,4 @@ -## App plugin configuration +# App plugin configuration 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. diff --git a/docs/user-guide/configuration-directories.md b/docs/user-guide/configuration-directories.md index 0ed4f7abce..660dfec551 100644 --- a/docs/user-guide/configuration-directories.md +++ b/docs/user-guide/configuration-directories.md @@ -1,4 +1,4 @@ -## Configuration Directories +# Configuration Directories When running, the App Server will access the server's settings and read or modify the contents of its resource storage. All of this data is stored within a hierarchy of folders which correspond to scopes: - Product: The contents of this folder are not meant to be modified, but used as defaults for a product. diff --git a/docs/user-guide/logging-configuration.md b/docs/user-guide/logging-configuration.md index 8a2fb4c68d..c8c58d92eb 100644 --- a/docs/user-guide/logging-configuration.md +++ b/docs/user-guide/logging-configuration.md @@ -1,4 +1,4 @@ -## Logging configuration +# Logging configuration For more information, see [Logging Utility](../extend/extend-desktop/mvd-logutility.md). diff --git a/docs/user-guide/network-configuration.md b/docs/user-guide/network-configuration.md index ca34a71740..35a411c860 100644 --- a/docs/user-guide/network-configuration.md +++ b/docs/user-guide/network-configuration.md @@ -1,4 +1,4 @@ -## Network configuration +# Network configuration **Note:** The following attributes are to be defined in the Zowe configuration file. From 29251ad178e273b904f769d049aaf11c4cfcd0e1 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 11:16:15 +0530 Subject: [PATCH 11/57] Updating zss-configuration-1.md, using-multiple-zis-instances.md, controlling-access-to-apps.md Signed-off-by: arooshlele --- docs/user-guide/controlling-access-to-apps.md | 2 +- docs/user-guide/using-multiple-zis-instances.md | 2 +- docs/user-guide/zss-configuration-1.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/controlling-access-to-apps.md b/docs/user-guide/controlling-access-to-apps.md index f307493bad..e63e80fbe9 100644 --- a/docs/user-guide/controlling-access-to-apps.md +++ b/docs/user-guide/controlling-access-to-apps.md @@ -1,4 +1,4 @@ -## Controlling access to apps +# Controlling access to apps 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. diff --git a/docs/user-guide/using-multiple-zis-instances.md b/docs/user-guide/using-multiple-zis-instances.md index b93707d98d..5b058b829e 100644 --- a/docs/user-guide/using-multiple-zis-instances.md +++ b/docs/user-guide/using-multiple-zis-instances.md @@ -1,4 +1,4 @@ -## Using multiple ZIS instances +# 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. The following steps can be followed to point a Zowe instance at a particular ZIS server. diff --git a/docs/user-guide/zss-configuration-1.md b/docs/user-guide/zss-configuration-1.md index 513e0dd8f4..521e48985c 100644 --- a/docs/user-guide/zss-configuration-1.md +++ b/docs/user-guide/zss-configuration-1.md @@ -1,4 +1,4 @@ -## ZSS configuration +# ZSS configuration ZSS provides APIs that any server or client can use. By default, the Zowe Desktop includes Apps which rely upon ZSS APIs, and therefore it's recommended that whenever the `app-server` is enabled in the Zowe YAML, that `zss` is also enabled. From 0ffc7de0b6de545276b5936ca0e461e6cf074a88 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 11:18:16 +0530 Subject: [PATCH 12/57] Updating controlling-access-to-dataservices.md, customizing-security-plugins.md Signed-off-by: arooshlele --- docs/user-guide/controlling-access-to-dataservices.md | 2 +- docs/user-guide/customizing-security-plugins.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/controlling-access-to-dataservices.md b/docs/user-guide/controlling-access-to-dataservices.md index 393c8b3eda..6828e77f75 100644 --- a/docs/user-guide/controlling-access-to-dataservices.md +++ b/docs/user-guide/controlling-access-to-dataservices.md @@ -1,4 +1,4 @@ -## Controlling access to dataservices +# 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 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. diff --git a/docs/user-guide/customizing-security-plugins.md b/docs/user-guide/customizing-security-plugins.md index 4ce4739775..dc139abaa7 100644 --- a/docs/user-guide/customizing-security-plugins.md +++ b/docs/user-guide/customizing-security-plugins.md @@ -1,4 +1,4 @@ -## Customizing Security Plugins +# Customizing Security Plugins By default, the `app-server` handles security questions by utilizing either the API Mediation Layer, or ZSS, depending on which is present. If the API Mediation Layer is present, it is used to establish an SSO session which ZSS also respects. When RBAC is enabled, ZSS is queried for authorization questions. From 5e3495e72af0d9ac68f32b02b5539aa07b741c41 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 11:19:21 +0530 Subject: [PATCH 13/57] Updating administering-the-servers-and-plugins-using-an-api.md Signed-off-by: arooshlele --- .../administering-the-servers-and-plugins-using-an-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md b/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md index d69e4ae4af..a1337adb3f 100644 --- a/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md +++ b/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md @@ -1,4 +1,4 @@ -## Administering the servers and plugins using an API +# Administering the servers and plugins using an API The App Server has a REST API to retrieve and edit both the App Server and ZSS server configuration values, and list, add, update, and delete plugins. Most of the features require RBAC to be enabled and for your user to have RBAC access to utilize these endpoints. For more information see documentation on how to [use RBAC](https://docs.zowe.org/stable/user-guide/mvd-configuration.html#controlling-access-to-dataservices) The API returns the following information in a JSON response: From d8fe4f08a308ce911b945d74c41d68a6b45ac093 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 11:20:22 +0530 Subject: [PATCH 14/57] managing-cluster-mode-for-app-server.md Signed-off-by: arooshlele --- docs/user-guide/managing-cluster-mode-for-app-server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/managing-cluster-mode-for-app-server.md b/docs/user-guide/managing-cluster-mode-for-app-server.md index 9cd9282187..0b85620026 100644 --- a/docs/user-guide/managing-cluster-mode-for-app-server.md +++ b/docs/user-guide/managing-cluster-mode-for-app-server.md @@ -1,4 +1,4 @@ -## Managing Cluster Mode for app-server +# Managing Cluster Mode for app-server On the Zowe servers, the component "app-server" has an environment variable "ZLUX_NO_CLUSTER" which controls whether or not it uses cluster mode. Cluster mode is enabled by default. However, you might need to disable cluster mode under certain circumstances. When cluster mode is disabled, make sure you are aware of the potential drawbacks and benefit. From be76cdbb92fb543708aa34877592860b3d19a30e Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 11:33:01 +0530 Subject: [PATCH 15/57] Updating configuration-file.md Signed-off-by: arooshlele --- docs/user-guide/configuration-file.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/configuration-file.md b/docs/user-guide/configuration-file.md index a2227946fc..32d7520e8e 100644 --- a/docs/user-guide/configuration-file.md +++ b/docs/user-guide/configuration-file.md @@ -1,10 +1,10 @@ # Configuration file -### app-server configuration +## 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-app-server/blob/v3.x/staging/schemas/app-server-config.json) which describes attributes that can be specified within the configuration file section `components.app-server` -### zss configuration +## 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. From cf2680e134c98f5fa0309e46e0bc53238e9e6956 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 11:50:16 +0530 Subject: [PATCH 16/57] Updated setting-up-terminal-app-plugins.md Signed-off-by: arooshlele --- docs/user-guide/setting-up-terminal-app-plugins.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/setting-up-terminal-app-plugins.md b/docs/user-guide/setting-up-terminal-app-plugins.md index 6a09e10a9f..a6ba45a08e 100644 --- a/docs/user-guide/setting-up-terminal-app-plugins.md +++ b/docs/user-guide/setting-up-terminal-app-plugins.md @@ -2,7 +2,7 @@ Follow these optional steps to configure the default connection to open for the terminal app plugins. -### Setting up the TN3270 mainframe terminal app plugin +## Setting up the TN3270 mainframe terminal app plugin 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: @@ -14,7 +14,7 @@ The file `_defaultTN3270.json` within the `tn3270-ng2` app folder `/config/stora } ``` -### Setting up the VT Terminal app plugin +## Setting up the VT Terminal app plugin 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: From 3f68ee48b0fb94cab40d25a6d81e07f1eb52af25 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 13:08:18 +0530 Subject: [PATCH 17/57] Updating network-configuration.md Signed-off-by: arooshlele --- docs/user-guide/network-configuration.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/network-configuration.md b/docs/user-guide/network-configuration.md index 35a411c860..295fafbfd1 100644 --- a/docs/user-guide/network-configuration.md +++ b/docs/user-guide/network-configuration.md @@ -4,7 +4,7 @@ The App Server and ZSS both can be accessed over HTTPS, either natively or via AT-TLS by setting appropriate AT-TLS rules and Zowe YAML assignments. When using native HTTPS, the TLS properties can be further customized within the YAML. -### Port configuration +## Port configuration The Zowe YAML property `components..port` can be used to set the port for any Zowe server. By default, the following is used but can be overridden: @@ -16,18 +16,18 @@ components: port: 7557 ``` -### IP configuration +## IP configuration By default, all Zowe servers listen on the IP address `0.0.0.0`. This can be customized. The Zowe YAML property `zowe.network.server.tls.listenAddresses` can be used to instruct both `app-server` and `zss` of which IP to listen on. This property can be nested within each component if it is desired to customize them individually. Alternatively, TCPIP port rules can be used to control the assignment of `0.0.0.0` into a particular alternative IP address. [You can read more about this in the network requirements page](./address-network-requirements.md). -### Native TLS +## Native TLS Both `app-server` and `zss` server components default to using HTTPS without the need for AT-TLS. AT-TLS is also possible. When using the native TLS, attributes such as TLS version and ciphers can be customized within the `zowe.network.server.tls` and `zowe.network.client.tls` objects of the Zowe configuration. These objects can also be placed within the `components.zss` and `components.app-server` objects, such as `components.zss.zowe.network.server.tls` in order to individually customize each server TLS configuration. For more information, read [TLS configuration](./tls-configuration.md). -### AT-TLS +## AT-TLS You can instruct Zowe servers to expect TLS using the property `zowe.network.server.tls.attls: true`. Use this property is to set AT-TLS for all Zowe servers. For more granular control, you can set the following section in the yaml file: @@ -46,7 +46,7 @@ components: This configuration instructs only the `app-server` component to expect AT-TLS for both inbound and outbound traffic. Similarly, set the parameter `zowe.network.server.tls.attls` to `true` for the `zss` component. Use `zowe.network.server.tls.attls: true` to instruct both servers to expect AT-TLS altogether. For more information, see [Configuring AT-TLS for Zowe server](./configuring-at-tls-for-zowe-server.md). -#### AT-TLS Rule Suggestions +### AT-TLS Rule Suggestions The `app-server` and `zss` components of Zowe are servers that may accept incoming connections from each other, other Zowe servers, and clients outside z/OS such as browsers either directly or indirectly such as when API ML is used. @@ -61,7 +61,7 @@ The Inbound rules can have a HandshakeRole of Server or ServerWithClientAuth. -### Native TLS +## Native TLS The configuration object `zowe.network.server.tls` and `zowe.network.client.tls` can be set to control all Zowe components, or just `app-server` or `zss` but nesting the object within them. This object can control ciphers by listing IANA cipher names, minimum and maximum TLS levels, and for some servers even curves can be customized via a list. From df183f177c091415d399fcdb97271be9b008145c Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 13:09:46 +0530 Subject: [PATCH 18/57] Updated logging-configuration.md Signed-off-by: arooshlele --- docs/user-guide/logging-configuration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/logging-configuration.md b/docs/user-guide/logging-configuration.md index c8c58d92eb..a91fe0c6d7 100644 --- a/docs/user-guide/logging-configuration.md +++ b/docs/user-guide/logging-configuration.md @@ -2,7 +2,7 @@ For more information, see [Logging Utility](../extend/extend-desktop/mvd-logutility.md). -### Enabling tracing +## 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). @@ -26,18 +26,18 @@ zss: All settings are optional. -### Log files +## 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 +### 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 +### 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. From 10adb5d39d0fe2ef603c8b6eb30d24bddda95e7b Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 13:11:00 +0530 Subject: [PATCH 19/57] Updating zss-configuration-1.md Signed-off-by: arooshlele --- docs/user-guide/zss-configuration-1.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/user-guide/zss-configuration-1.md b/docs/user-guide/zss-configuration-1.md index 521e48985c..cf629b9ce8 100644 --- a/docs/user-guide/zss-configuration-1.md +++ b/docs/user-guide/zss-configuration-1.md @@ -3,11 +3,11 @@ ZSS provides APIs that any server or client can use. By default, the Zowe Desktop includes Apps which rely upon ZSS APIs, and therefore it's recommended that whenever the `app-server` is enabled in the Zowe YAML, that `zss` is also enabled. -### ZSS 64 or 31 bit modes +## ZSS 64 or 31 bit modes 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. -#### Verifying which ZSS mode is in use +### Verifying which ZSS mode is in use 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: @@ -17,7 +17,7 @@ Or `ZWES1013I ZSS Server has started. Version 3.0.0 31-bit` -#### Verifying which ZSS mode plugins support +### 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. @@ -27,11 +27,11 @@ If the service has the property `libraryName64`, then it supports 64 bit. If it 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 +### 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. -#### Customizing ZSS session duration +### Customizing ZSS session duration In a standard Zowe installation, all Zowe servers utilize the API Mediation Layer's token-based, single-sign on authentication. This authentication in turn cooperates with z/OSMF, and the session duration is typically that of z/OSMF's, which defaults to 8 hours before the session expires. In that situation, customization of session duration is best done by customizing z/OSMF's session duration, as a part of its Liberty configuration. From 3ab74b276fd30f9bba90c1c13c3164ad107e83fe Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 13:12:27 +0530 Subject: [PATCH 20/57] Updated controlling-access-to-apps.md Signed-off-by: arooshlele --- docs/user-guide/controlling-access-to-apps.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/controlling-access-to-apps.md b/docs/user-guide/controlling-access-to-apps.md index e63e80fbe9..b2489f7a99 100644 --- a/docs/user-guide/controlling-access-to-apps.md +++ b/docs/user-guide/controlling-access-to-apps.md @@ -6,13 +6,13 @@ 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. -### Enabling RBAC +## Enabling RBAC 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* and *components.app-server.dataserviceAuthentication.rbac* variables to `true` in the Zowe configuration file. -### Controlling app access for all users +## Controlling app access for all users **Note:** - `` variable comes from the Zowe configuration file. @@ -33,7 +33,7 @@ By default, RBAC is disabled and all authenticated Zowe users can access all dat 5. [Restart the app server](start-zowe-zos.md). -### Controlling app access for individual users +## Controlling app access for individual users 1. Enable RBAC. From 961e015aaf2228baa15e702d10fa0f4e727c15ea Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 13:13:41 +0530 Subject: [PATCH 21/57] Updated controlling-access-to-dataservices.md Signed-off-by: arooshlele --- docs/user-guide/controlling-access-to-dataservices.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/controlling-access-to-dataservices.md b/docs/user-guide/controlling-access-to-dataservices.md index 6828e77f75..9047215b5b 100644 --- a/docs/user-guide/controlling-access-to-dataservices.md +++ b/docs/user-guide/controlling-access-to-dataservices.md @@ -3,7 +3,7 @@ To apply role-based access control (RBAC) to dataservice endpoints, you must ena 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. -### Creating authorization profiles +## 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. Endpoints are identified by URIs in the following format: @@ -26,14 +26,14 @@ For example, to issue a POST request to the dataservice endpoint documented abov For configuration dataservice endpoint profiles use the service code `CFG`. For core dataservice endpoints use `COR`. For all other dataservice endpoints use `SVC`. -### Creating generic authorization profiles +## Creating generic authorization profiles Some endpoints can generate an unlimited number of URIs. For example, an endpoint that performs a DELETE action on any file would generate a different URI for each file, and users can create an unlimited number of files. To apply RBAC to this type of endpoint you must create a generic profile, for example: `ZLUX.1.COR.ORG_ZOWE_FOO.BAZ.DELETE.**` You can create generic profile names using wildcards, such as asterisks (*). For information on generic profile naming, see [IBM documentation](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.icha100/egnoff.htm). -### Configuring basic authorization +## Configuring basic authorization The following are recommended for basic authorization: @@ -43,7 +43,7 @@ The following are recommended for basic authorization: - To give non-administrators all access to user, create the following profile and give them UPDATE access to it: `ZLUX.1.CFG.*.*.USER.**` -### Endpoint URL length limitations +## Endpoint URL length limitations SAF profiles cannot contain more than 246 characters. If the path section of an endpoint URL is long enough that the profile name exceeds the limit, the path is trimmed to only include elements that do not exceed the limit. To avoid this issue, we recommend that appliction developers maintain relatively short endpoint URL paths. For information on endpoint URLs, see [Using dataservices with RBAC](../extend/extend-desktop/mvd-dataservices.md#using-dataservices-with-rbac) From 3e42f8b112b99db4f503cd73472a5c6a539e2c77 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 13:14:55 +0530 Subject: [PATCH 22/57] Updated customizing-security-plugins.md Signed-off-by: arooshlele --- docs/user-guide/customizing-security-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/customizing-security-plugins.md b/docs/user-guide/customizing-security-plugins.md index dc139abaa7..98f82542fd 100644 --- a/docs/user-guide/customizing-security-plugins.md +++ b/docs/user-guide/customizing-security-plugins.md @@ -7,7 +7,7 @@ Security plugins can be installed as part of Zowe extensions, and `app-server` c Different security plugins could be used to operate in different environments, with different security systems, or with different session characteristics. For more information, [read the extender's guide on security plugins](../extend/extend-desktop/mvd-authentication-api.md) -### Session duration and expiration +## Session duration and expiration After successful authentication, a Zowe Desktop session is created by authentication plugins. From d2828a649204eb8335b815116e59458f2cbf622e Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 18 Nov 2025 13:16:42 +0530 Subject: [PATCH 23/57] Updated managing-cluster-mode-for-app-server.md Signed-off-by: arooshlele --- docs/user-guide/managing-cluster-mode-for-app-server.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/managing-cluster-mode-for-app-server.md b/docs/user-guide/managing-cluster-mode-for-app-server.md index 0b85620026..f5c6c56834 100644 --- a/docs/user-guide/managing-cluster-mode-for-app-server.md +++ b/docs/user-guide/managing-cluster-mode-for-app-server.md @@ -8,11 +8,11 @@ When you **disable** cluster mode, you will lose the following benefits: 2. **Reduced downtime during unexpected exceptions:** The low-downtime characteristic, where only one request is interrupted compared to around 15 seconds of downtime, is compromised. -### To turn the cluster mode on +## To turn the cluster mode on - Do NOT include the `zowe.environments.ZLUX_NO_CLUSTER `in the `zowe.yaml` file. -### To turn the cluster mode off +## To turn the cluster mode off - Include `zowe.environments.ZLUX_NO_CLUSTER=1` in the `zowe.yaml` file. From ed8e63d13c51a80547f414df12e5e528863945b5 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 8 Dec 2025 19:23:43 +0530 Subject: [PATCH 24/57] Update controlling-access-to-dataservices.md Signed-off-by: ArooshLele --- docs/user-guide/controlling-access-to-dataservices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/controlling-access-to-dataservices.md b/docs/user-guide/controlling-access-to-dataservices.md index 9047215b5b..e2a479eccb 100644 --- a/docs/user-guide/controlling-access-to-dataservices.md +++ b/docs/user-guide/controlling-access-to-dataservices.md @@ -44,7 +44,7 @@ The following are recommended for basic authorization: ## Endpoint URL length limitations -SAF profiles cannot contain more than 246 characters. If the path section of an endpoint URL is long enough that the profile name exceeds the limit, the path is trimmed to only include elements that do not exceed the limit. To avoid this issue, we recommend that appliction developers maintain relatively short endpoint URL paths. +SAF profiles cannot contain more than 246 characters. If the path section of an endpoint URL is long enough that the profile name exceeds the limit, the path is trimmed to only include elements that do not exceed the limit. To avoid this issue, we recommend that application developers maintain relatively short endpoint URL paths. For information on endpoint URLs, see [Using dataservices with RBAC](../extend/extend-desktop/mvd-dataservices.md#using-dataservices-with-rbac) From a0bd8ebd6f6b5106b90e97f4cd94e641e9354483 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 8 Dec 2025 19:25:44 +0530 Subject: [PATCH 25/57] Update customizing-security-plugins.md Signed-off-by: ArooshLele --- docs/user-guide/customizing-security-plugins.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/customizing-security-plugins.md b/docs/user-guide/customizing-security-plugins.md index 98f82542fd..5904e9d6d8 100644 --- a/docs/user-guide/customizing-security-plugins.md +++ b/docs/user-guide/customizing-security-plugins.md @@ -13,8 +13,8 @@ After successful authentication, a Zowe Desktop session is created by authentica The duration of the session is determined by the plugin used. Some plugins are capable of renewing the session prior to expiration, while others may have a fixed session length. -The session duration and expiration behavior of the default security plugin, `sso-auth`, is determined by API Medation Layer configuration if present, and otherwise upon ZSS configuration. -If API Medation Layer is enabled, by default it will use z/OSMF as the session provider and the session duration will be based upon z/OSMF settings. [You can read more about API Mediation Layer providers here](authentication-providers-for-apiml.md). +The session duration and expiration behavior of the default security plugin, `sso-auth`, is determined by API Mediation Layer configuration if present, and otherwise upon ZSS configuration. +If API Mediation Layer is enabled, by default it will use z/OSMF as the session provider and the session duration will be based upon z/OSMF settings. [You can read more about API Mediation Layer providers here](authentication-providers-for-apiml.md). If the API Mediation Layer is not enabled, you can [use or customize ZSS's default session duration of one hour](#customizing-zss-session-duration). When a session expires, the credentials used for the initial login are likely to be invalid for re-use, since MFA credentials are often one-time-use or time-based. From 116e01cdb94c3ebc18d63e56d5a9395d151ccd9a Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 8 Dec 2025 19:27:35 +0530 Subject: [PATCH 26/57] Update logging-configuration.md Signed-off-by: ArooshLele --- docs/user-guide/logging-configuration.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/logging-configuration.md b/docs/user-guide/logging-configuration.md index a91fe0c6d7..6cfa47414f 100644 --- a/docs/user-guide/logging-configuration.md +++ b/docs/user-guide/logging-configuration.md @@ -8,17 +8,17 @@ To obtain more information about how a server is working, you can enable tracing For example: -``` -app-server: - {...} +```yaml +components: + app-server: logLevels: _zsf.routing: 0 _zsf.install: 0 ``` -``` -zss: - {...} +```yaml +components: + zss: logLevels: _zss.traceLevel: 0 _zss.fileTrace: 1 From 63325bdd8b79b015058d70a2570be47f8e0982dd Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 8 Dec 2025 19:32:08 +0530 Subject: [PATCH 27/57] Update setting-up-terminal-app-plugins.md Signed-off-by: ArooshLele --- docs/user-guide/setting-up-terminal-app-plugins.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/user-guide/setting-up-terminal-app-plugins.md b/docs/user-guide/setting-up-terminal-app-plugins.md index a6ba45a08e..6802aa9617 100644 --- a/docs/user-guide/setting-up-terminal-app-plugins.md +++ b/docs/user-guide/setting-up-terminal-app-plugins.md @@ -7,11 +7,13 @@ Follow these optional steps to configure the default connection to open for the 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": "security": { type: <"telnet" or "tls"> } +} ``` ## Setting up the VT Terminal app plugin @@ -19,10 +21,12 @@ The file `_defaultTN3270.json` within the `tn3270-ng2` app folder `/config/stora 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": "security": { type: <"telnet" or "ssh"> } +} ``` From 6953d7b14c9585df171d1d5c58d746b1455de3a9 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 8 Dec 2025 19:41:47 +0530 Subject: [PATCH 28/57] Update setting-up-terminal-app-plugins.md Signed-off-by: ArooshLele --- docs/user-guide/setting-up-terminal-app-plugins.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/setting-up-terminal-app-plugins.md b/docs/user-guide/setting-up-terminal-app-plugins.md index 6802aa9617..4c8eaae790 100644 --- a/docs/user-guide/setting-up-terminal-app-plugins.md +++ b/docs/user-guide/setting-up-terminal-app-plugins.md @@ -1,10 +1,10 @@ # Setting up terminal app plugins -Follow these optional steps to configure the default connection to open for the 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 -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: +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) after 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: ``` { From 363481c43bf2273bbd2dce8ed814d70d33f3c91a Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 9 Dec 2025 11:25:52 +0530 Subject: [PATCH 29/57] Updating sidebars.js file Signed-off-by: arooshlele --- sidebars.js | 50 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/sidebars.js b/sidebars.js index b3eb2d4c13..815978b7ca 100644 --- a/sidebars.js +++ b/sidebars.js @@ -344,7 +344,55 @@ module.exports = { type: "category", label: "Advanced Application Framework Configuration", link: { type: "doc", id: "user-guide/mvd-configuration", }, collapsed: false, - items: ["user-guide/accessing-zss", + items: [ + type: "category", + label: "app-server", link: { type: "doc", id: "user-guide/managing-cluster-mode-for-app-server", }, + collapsed: false, + "items": [ + "user-guide/managing-cluster-mode-for-app-server", + ] + + type: "category", + label: "zss", link: { type: "doc", id: "user-guide/accessing-zss", }, + collapsed: false, + items: [ + "items": [ + "user-guide/accessing-zss", + "user-guide/zss-configuration-1", + + + type: "category", + label: "zis", link: { type: "doc", id: "user-guide/using-multiple-zis-instances", }, + collapsed: false, + items: [ + "user-guide/using-multiple-zis-instances", + ] + + + type: "category", + label: "apps", link: { type: "doc", id: "user-guide/app-plugin-configuration", }, + collapsed: false, + items: [ + "user-guide/app-plugin-configuration", + "user-guide/setting-up-terminal-app-plugins", + ] + + + type: "category", + label: "administration", link: { type: "doc", id: "user-guide/controlling-access-to-apps", }, + collapsed: false, + items: [ + "user-guide/controlling-access-to-dataservices", + "user-guide/customizing-security-plugins", + "user-guide/administering-the-servers-and-plugins-using-an-api", + "user-guide/configuration-file", + "user-guide/logging-configuration", + "user-guide/network-configuration", + + ] + + + "user-guide/accessing-zss", "user-guide/configuration-file", "user-guide/configuring-the-framework-as-a-mediation-layer-client", "user-guide/setting-up-terminal-app-plugins", From fe19f789d03ee3e237869b494fd1882e88e29e25 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 9 Dec 2025 12:14:06 +0530 Subject: [PATCH 30/57] Updating sidebars.js file Signed-off-by: arooshlele --- sidebars.js | 38 +++++++++++++------------------------- 1 file changed, 13 insertions(+), 25 deletions(-) diff --git a/sidebars.js b/sidebars.js index 815978b7ca..e1dacb4202 100644 --- a/sidebars.js +++ b/sidebars.js @@ -342,45 +342,34 @@ module.exports = { "user-guide/mvd-configuration", { type: "category", - label: "Advanced Application Framework Configuration", link: { type: "doc", id: "user-guide/mvd-configuration", }, + label: "Advanced Application Framework Configuration", + link: { type: "doc", id: "user-guide/mvd-configuration", }, collapsed: false, items: [ - type: "category", - label: "app-server", link: { type: "doc", id: "user-guide/managing-cluster-mode-for-app-server", }, - collapsed: false, - "items": [ - "user-guide/managing-cluster-mode-for-app-server", - ] + label: "app-server", link: { type: "doc", id: "user-guide/managing-cluster-mode-for-app-server", }, + collapsed: false, + items: [ + "user-guide/managing-cluster-mode-for-app-server",] - type: "category", - label: "zss", link: { type: "doc", id: "user-guide/accessing-zss", }, - collapsed: false, - items: [ - "items": [ + label: "zss", link: { type: "doc", id: "user-guide/accessing-zss", }, + items: [ "user-guide/accessing-zss", "user-guide/zss-configuration-1", + ] - - type: "category", - label: "zis", link: { type: "doc", id: "user-guide/using-multiple-zis-instances", }, - collapsed: false, - items: [ + label: "zis", link: { type: "doc", id: "user-guide/using-multiple-zis-instances", }, + items: [ "user-guide/using-multiple-zis-instances", - ] + ] - - type: "category", label: "apps", link: { type: "doc", id: "user-guide/app-plugin-configuration", }, - collapsed: false, items: [ "user-guide/app-plugin-configuration", "user-guide/setting-up-terminal-app-plugins", - ] - + ] type: "category", label: "administration", link: { type: "doc", id: "user-guide/controlling-access-to-apps", }, - collapsed: false, items: [ "user-guide/controlling-access-to-dataservices", "user-guide/customizing-security-plugins", @@ -388,7 +377,6 @@ module.exports = { "user-guide/configuration-file", "user-guide/logging-configuration", "user-guide/network-configuration", - ] From 82c9472eb63810bf2f00f44651f7f677134ed8a7 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Wed, 10 Dec 2025 12:21:38 +0530 Subject: [PATCH 31/57] Updating sidebars.js file Signed-off-by: arooshlele --- sidebars.js | 40 ---------------------------------------- 1 file changed, 40 deletions(-) diff --git a/sidebars.js b/sidebars.js index e1dacb4202..c5f8bda0c0 100644 --- a/sidebars.js +++ b/sidebars.js @@ -340,46 +340,6 @@ module.exports = { "user-guide/configmgr-using", "user-guide/install-configure-zos-extensions", "user-guide/mvd-configuration", - { - type: "category", - label: "Advanced Application Framework Configuration", - link: { type: "doc", id: "user-guide/mvd-configuration", }, - collapsed: false, - items: [ - label: "app-server", link: { type: "doc", id: "user-guide/managing-cluster-mode-for-app-server", }, - collapsed: false, - items: [ - "user-guide/managing-cluster-mode-for-app-server",] - - label: "zss", link: { type: "doc", id: "user-guide/accessing-zss", }, - items: [ - "user-guide/accessing-zss", - "user-guide/zss-configuration-1", - ] - - label: "zis", link: { type: "doc", id: "user-guide/using-multiple-zis-instances", }, - items: [ - "user-guide/using-multiple-zis-instances", - ] - - label: "apps", link: { type: "doc", id: "user-guide/app-plugin-configuration", }, - items: [ - "user-guide/app-plugin-configuration", - "user-guide/setting-up-terminal-app-plugins", - ] - - type: "category", - label: "administration", link: { type: "doc", id: "user-guide/controlling-access-to-apps", }, - items: [ - "user-guide/controlling-access-to-dataservices", - "user-guide/customizing-security-plugins", - "user-guide/administering-the-servers-and-plugins-using-an-api", - "user-guide/configuration-file", - "user-guide/logging-configuration", - "user-guide/network-configuration", - ] - - "user-guide/accessing-zss", "user-guide/configuration-file", "user-guide/configuring-the-framework-as-a-mediation-layer-client", From 89ac7f486852c3ec8f4f9e923998405477d1a98e Mon Sep 17 00:00:00 2001 From: arooshlele Date: Wed, 10 Dec 2025 14:31:08 +0530 Subject: [PATCH 32/57] Updating sidebars.js file Signed-off-by: arooshlele --- sidebars.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sidebars.js b/sidebars.js index c5f8bda0c0..92bf857e57 100644 --- a/sidebars.js +++ b/sidebars.js @@ -340,8 +340,8 @@ module.exports = { "user-guide/configmgr-using", "user-guide/install-configure-zos-extensions", "user-guide/mvd-configuration", - "user-guide/accessing-zss", - "user-guide/configuration-file", + "user-guide/accessing-zss", + "user-guide/configuration-file", "user-guide/configuring-the-framework-as-a-mediation-layer-client", "user-guide/setting-up-terminal-app-plugins", "user-guide/network-configuration", From 9436996baf43932b9cef71cc7b16596f7e75b55a Mon Sep 17 00:00:00 2001 From: arooshlele Date: Wed, 10 Dec 2025 15:07:15 +0530 Subject: [PATCH 33/57] Updating sidebars.js file Signed-off-by: arooshlele --- sidebars.js | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/sidebars.js b/sidebars.js index 92bf857e57..ac3a02673f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -342,19 +342,19 @@ module.exports = { "user-guide/mvd-configuration", "user-guide/accessing-zss", "user-guide/configuration-file", - "user-guide/configuring-the-framework-as-a-mediation-layer-client", - "user-guide/setting-up-terminal-app-plugins", - "user-guide/network-configuration", - "user-guide/configuration-directories", - "user-guide/app-plugin-configuration", - "user-guide/logging-configuration", - "user-guide/zss-configuration-1", - "user-guide/using-multiple-zis-instances", - "user-guide/controlling-access-to-apps", - "user-guide/controlling-access-to-dataservices", - "user-guide/customizing-security-plugins", - "user-guide/administering-the-servers-and-plugins-using-an-api", - "user-guide/managing-cluster-mode-for-app-server", + "user-guide/configuring-the-framework-as-a-mediation-layer-client", + "user-guide/setting-up-terminal-app-plugins", + "user-guide/network-configuration", + "user-guide/configuration-directories", + "user-guide/app-plugin-configuration", + "user-guide/logging-configuration", + "user-guide/zss-configuration-1", + "user-guide/using-multiple-zis-instances", + "user-guide/controlling-access-to-apps", + "user-guide/controlling-access-to-dataservices", + "user-guide/customizing-security-plugins", + "user-guide/administering-the-servers-and-plugins-using-an-api", + "user-guide/managing-cluster-mode-for-app-server", ], }, ], From b8928eabe97228509d089c6b88e319cb15b7a05a Mon Sep 17 00:00:00 2001 From: arooshlele Date: Fri, 12 Dec 2025 15:50:41 +0530 Subject: [PATCH 34/57] Updating sidebars.js file Signed-off-by: arooshlele --- sidebars.js | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/sidebars.js b/sidebars.js index ac3a02673f..a1a6551bf8 100644 --- a/sidebars.js +++ b/sidebars.js @@ -340,6 +340,26 @@ module.exports = { "user-guide/configmgr-using", "user-guide/install-configure-zos-extensions", "user-guide/mvd-configuration", + { + "type": "category", + "items": [ + "user-guide/accessing-zss", + "user-guide/configuration-file", + "user-guide/configuring-the-framework-as-a-mediation-layer-client", + "user-guide/setting-up-terminal-app-plugins", + "user-guide/network-configuration", + "user-guide/configuration-directories", + "user-guide/app-plugin-configuration", + "user-guide/logging-configuration", + "user-guide/zss-configuration-1", + "user-guide/using-multiple-zis-instances", + "user-guide/controlling-access-to-apps", + "user-guide/controlling-access-to-dataservices", + "user-guide/customizing-security-plugins", + "user-guide/administering-the-servers-and-plugins-using-an-api", + "user-guide/managing-cluster-mode-for-app-server", + ] + } "user-guide/accessing-zss", "user-guide/configuration-file", "user-guide/configuring-the-framework-as-a-mediation-layer-client", From 971ece3b5df27bf28cb661ad19f772a958cfad46 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Fri, 12 Dec 2025 16:09:27 +0530 Subject: [PATCH 35/57] Updating sidebars.js file Signed-off-by: arooshlele --- sidebars.js | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/sidebars.js b/sidebars.js index a1a6551bf8..539f611222 100644 --- a/sidebars.js +++ b/sidebars.js @@ -339,27 +339,31 @@ module.exports = { }, "user-guide/configmgr-using", "user-guide/install-configure-zos-extensions", - "user-guide/mvd-configuration", { "type": "category", + "label" "Advanced Application Framework Configuration", + "user-guide/mvd-configuration", "items": [ - "user-guide/accessing-zss", - "user-guide/configuration-file", - "user-guide/configuring-the-framework-as-a-mediation-layer-client", - "user-guide/setting-up-terminal-app-plugins", - "user-guide/network-configuration", - "user-guide/configuration-directories", - "user-guide/app-plugin-configuration", - "user-guide/logging-configuration", - "user-guide/zss-configuration-1", - "user-guide/using-multiple-zis-instances", - "user-guide/controlling-access-to-apps", - "user-guide/controlling-access-to-dataservices", - "user-guide/customizing-security-plugins", - "user-guide/administering-the-servers-and-plugins-using-an-api", - "user-guide/managing-cluster-mode-for-app-server", + "user-guide/mvd-configuration", + "user-guide/accessing-zss", + "user-guide/configuration-file", + "user-guide/configuring-the-framework-as-a-mediation-layer-client", + "user-guide/setting-up-terminal-app-plugins", + "user-guide/network-configuration", + "user-guide/configuration-directories", + "user-guide/app-plugin-configuration", + "user-guide/logging-configuration", + "user-guide/zss-configuration-1", + "user-guide/using-multiple-zis-instances", + "user-guide/controlling-access-to-apps", + "user-guide/controlling-access-to-dataservices", + "user-guide/customizing-security-plugins", + "user-guide/administering-the-servers-and-plugins-using-an-api", + "user-guide/managing-cluster-mode-for-app-server", ] } + + "user-guide/mvd-configuration", "user-guide/accessing-zss", "user-guide/configuration-file", "user-guide/configuring-the-framework-as-a-mediation-layer-client", From 0669bfc9fa6e66aa2bb2dfa380a43b4d26d171d7 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Fri, 12 Dec 2025 16:35:07 +0530 Subject: [PATCH 36/57] Updating sidebars.js file Signed-off-by: arooshlele --- sidebars.js | 18 +----------------- 1 file changed, 1 insertion(+), 17 deletions(-) diff --git a/sidebars.js b/sidebars.js index 539f611222..6cdaafeb3e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -341,7 +341,6 @@ module.exports = { "user-guide/install-configure-zos-extensions", { "type": "category", - "label" "Advanced Application Framework Configuration", "user-guide/mvd-configuration", "items": [ "user-guide/mvd-configuration", @@ -363,22 +362,7 @@ module.exports = { ] } - "user-guide/mvd-configuration", - "user-guide/accessing-zss", - "user-guide/configuration-file", - "user-guide/configuring-the-framework-as-a-mediation-layer-client", - "user-guide/setting-up-terminal-app-plugins", - "user-guide/network-configuration", - "user-guide/configuration-directories", - "user-guide/app-plugin-configuration", - "user-guide/logging-configuration", - "user-guide/zss-configuration-1", - "user-guide/using-multiple-zis-instances", - "user-guide/controlling-access-to-apps", - "user-guide/controlling-access-to-dataservices", - "user-guide/customizing-security-plugins", - "user-guide/administering-the-servers-and-plugins-using-an-api", - "user-guide/managing-cluster-mode-for-app-server", + ], }, ], From 41657ffe37dd97d3ef7f639c225fb82f8e852728 Mon Sep 17 00:00:00 2001 From: arooshlele Date: Fri, 12 Dec 2025 17:08:41 +0530 Subject: [PATCH 37/57] Updating sidebars.js file Signed-off-by: arooshlele --- sidebars.js | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/sidebars.js b/sidebars.js index 6cdaafeb3e..5ccb152853 100644 --- a/sidebars.js +++ b/sidebars.js @@ -340,9 +340,10 @@ module.exports = { "user-guide/configmgr-using", "user-guide/install-configure-zos-extensions", { - "type": "category", - "user-guide/mvd-configuration", - "items": [ + type: "category", + label: "Advanced Application Framework Configuration", + link: { "type": "doc", "id": "user-guide/mvd-configuration" }, + items: [ "user-guide/mvd-configuration", "user-guide/accessing-zss", "user-guide/configuration-file", From 5f1dda425e5c4430bd7bae89f5e611276980649a Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 17:54:13 +0530 Subject: [PATCH 38/57] Update accessing-zss.md (#4824) @anaxceron @gauravs-20 Signed-off-by: ArooshLele --- docs/user-guide/accessing-zss.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/accessing-zss.md b/docs/user-guide/accessing-zss.md index 421eb64964..e26f697027 100644 --- a/docs/user-guide/accessing-zss.md +++ b/docs/user-guide/accessing-zss.md @@ -1,10 +1,10 @@ # Accessing ZSS -The `zss` server should be accessed through the `gateway` when both are present. When both are ready, ZSS can be accessed from the API Mediation Layer Gateway, such as +The `zss` server should be accessed through the `gateway` when both are present. When both are ready, ZSS can be accessed from the API Mediation Layer Gateway, such as `https://:/zss/api/v1/`. -Although you access the ZSS server via the Gateway port, the ZSS server still needs a port assigned to it which is the value of the *components.zss.port* variable in the Zowe configuration file. +Although you access the ZSS server via the Gateway port, the ZSS server still needs a port assigned to it, which is the value of the *components.zss.port* variable in the Zowe configuration file. -If the mediation layer is not used, ZSS directly at `https://:/`. +If API ML is not used, you can access ZSS directly at `https://:/`. From 3d8d1f23b19cc8f906f73735e7c9ada9f7f0653d Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 17:56:05 +0530 Subject: [PATCH 39/57] Update controlling-access-to-apps.md (#4827) I made some minor edits. Signed-off-by: ArooshLele --- docs/user-guide/controlling-access-to-apps.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/controlling-access-to-apps.md b/docs/user-guide/controlling-access-to-apps.md index b2489f7a99..95ccbaa334 100644 --- a/docs/user-guide/controlling-access-to-apps.md +++ b/docs/user-guide/controlling-access-to-apps.md @@ -10,7 +10,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* and *components.app-server.dataserviceAuthentication.rbac* variables to `true` in the Zowe configuration file. +1. Set the `components.zss.dataserviceAuthentication.rbac` and `components.app-server.dataserviceAuthentication.rbac` variables to `true` in the Zowe configuration file. ## Controlling app access for all users @@ -23,11 +23,11 @@ By default, RBAC is disabled and all authenticated Zowe users can access all dat ``` /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: +3. Copy the `allowedPlugins.json` file and paste the file in the following location: ``` /app-server/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins ``` -4. 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 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. @@ -46,7 +46,7 @@ By default, RBAC is disabled and all authenticated Zowe users can access all dat ``` /components/app-server/share/zlux-app-server/defaults/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins ``` -6. Open the `allowedPlugins.json` file and specify apps that user can access. For example: +6. Open the `allowedPlugins.json` file, and specify apps that a user can access. For example: ```json { "allowedPlugins": [ From 84bcbcb30bf08382778a44f7258da8a72cce1f3f Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 17:56:44 +0530 Subject: [PATCH 40/57] Update administering-the-servers-and-plugins-using-an-api.md (#4825) Yes, I edited plugin to plug-in wherever applicable. In the table: -In the Description (right side) column, I removed "Returns" from the rows. -In the API (left side) column, I did not change plugin to plug-ins as that's the API's unique name, wherever applicable. Thanks ! Signed-off-by: ArooshLele --- ...ng-the-servers-and-plugins-using-an-api.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md b/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md index a1337adb3f..8127627877 100644 --- a/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md +++ b/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md @@ -1,25 +1,25 @@ -# Administering the servers and plugins using an API -The App Server has a REST API to retrieve and edit both the App Server and ZSS server configuration values, and list, add, update, and delete plugins. Most of the features require RBAC to be enabled and for your user to have RBAC access to utilize these endpoints. For more information see documentation on how to [use RBAC](https://docs.zowe.org/stable/user-guide/mvd-configuration.html#controlling-access-to-dataservices) +# Administering the servers and plug-ins using an API +The App Server has a REST API to retrieve and edit both the App Server and ZSS server configuration values, and list, add, update, and delete plug-ins. Most of the features require RBAC to be enabled and for your user to have RBAC access to utilize these endpoints. For more information, see the documentation on how to [use RBAC](https://docs.zowe.org/stable/user-guide/mvd-configuration.html#controlling-access-to-dataservices) The API returns the following information in a JSON response: | API | Description | | --------------------------------------------------------- | ------------------------------------------------------------ | -| /server (GET) | Returns a list of accessible server endpoints for the Zowe App Server. | -| /server/config (GET) | Returns the Zowe App Server configuration which follows [this specification](https://github.com/zowe/zlux-app-server/blob/v3.x/master/schemas/app-server-config.json). | -| /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 (GET) | A list of accessible server endpoints for the Zowe App Server. | +| /server/config (GET) | The Zowe App Server configuration which follows [this specification](https://github.com/zowe/zlux-app-server/blob/v3.x/master/schemas/app-server-config.json). | +| /server/log (GET) | The contents of the Zowe App Server log file. | +| /server/loglevels (GET) | The verbosity levels set in the Zowe App Server logger. | +| /server/environment (GET) | The 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 which follows [this specification](https://github.com/zowe/zss/blob/v3.x/staging/schemas/zss-config.json). | -| /server/agent/log (GET) | Returns the contents of the ZSS log file. | -| /server/agent/loglevels (GET) | Returns the verbosity levels of the ZSS logger. | -| /server/agent/environment (GET) | Returns ZSS environment information. | -| /server/logLevels/name/:componentName/level/:level (POST) | Specify the logger that you are using and a verbosity level. | -| /plugins (GET) | Returns a list of all plugins and their dataservices. | -| /plugins (PUT) | Adds a new plugin or upgrades an existing plugin. Only available in cluster mode (default). | -| /plugins/:id (DELETE) | Deletes a plugin. Only available in cluster mode (default). | +| /server/agent (GET) | A list of accessible server endpoints for the ZSS server. | +| /server/agent/config (GET) | The ZSS server configuration which follows [this specification](https://github.com/zowe/zss/blob/v3.x/staging/schemas/zss-config.json). | +| /server/agent/log (GET) | The contents of the ZSS log file. | +| /server/agent/loglevels (GET) | The verbosity levels of the ZSS logger. | +| /server/agent/environment (GET) | The ZSS environment information. | +| /server/logLevels/name/:componentName/level/:level (POST) | The logger that you are using and a verbosity level. | +| /plugins (GET) | A list of all plug-ins and their dataservices. | +| /plugins (PUT) | Adds a new plug-in or upgrades an existing plug-in. Only available in cluster mode (default). | +| /plugins/:id (DELETE) | Deletes a plug-in. Only available in cluster mode (default). | Swagger API documentation is provided in the `/components/app-server/share/zlux-app-server/doc/swagger/server-plugins-api.yaml` file. To see it in HTML format, you can paste the contents into the Swagger editor at https://editor.swagger.io/. From 876a8df9f83ee5feff60de5c77feb8c015e6826f Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 18:03:36 +0530 Subject: [PATCH 41/57] Update controlling-access-to-apps.md (#4828) Plugin changed to plug-in. Signed-off-by: ArooshLele --- docs/user-guide/controlling-access-to-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/controlling-access-to-apps.md b/docs/user-guide/controlling-access-to-apps.md index 95ccbaa334..c0b903ce5f 100644 --- a/docs/user-guide/controlling-access-to-apps.md +++ b/docs/user-guide/controlling-access-to-apps.md @@ -29,7 +29,7 @@ By default, RBAC is disabled and all authenticated Zowe users can access all dat ``` 4. Open the copied `allowedPlugins.json` file, and perform either of the following steps: - 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. + - To make an app available, copy an existing plug-in object and specify the app's values in the new object. Identifier and version attributes are required. 5. [Restart the app server](start-zowe-zos.md). From cd060c16f259580faade130dba8f4aba8fa4a12d Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 18:06:52 +0530 Subject: [PATCH 42/57] Update controlling-access-to-dataservices.md (#4829) Changed plugin to plug-in. Signed-off-by: ArooshLele --- docs/user-guide/controlling-access-to-dataservices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/controlling-access-to-dataservices.md b/docs/user-guide/controlling-access-to-dataservices.md index e2a479eccb..7ea95347df 100644 --- a/docs/user-guide/controlling-access-to-dataservices.md +++ b/docs/user-guide/controlling-access-to-dataservices.md @@ -1,7 +1,7 @@ # 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 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. +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 plug-in is a service dataservice. ## 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 a1a1543c0f72f1bba3a5e3ca5e85d99ce08e1de7 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 18:14:15 +0530 Subject: [PATCH 43/57] Update app-plugin-configuration.md (#4830) I edited plugin to plug-in, enclosed variable in backticks, rewrote Components as "components". (from Uppercase to Lowercase). Signed-off-by: ArooshLele --- docs/user-guide/app-plugin-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/app-plugin-configuration.md b/docs/user-guide/app-plugin-configuration.md index 77e7f0a5ac..4412b08c05 100644 --- a/docs/user-guide/app-plugin-configuration.md +++ b/docs/user-guide/app-plugin-configuration.md @@ -1,4 +1,4 @@ -# App plugin configuration +# App plug-in configuration -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. +The App framework will load plug-ins from components such as extensions based upon their enabled status in Zowe configuration. The server caches knowledge of these plug-ins in the `/app-server/plugins` folder. This location can be customized with the `components.app-server.pluginsDir` variable in the Zowe configuration file. From 080eac3c62c7d8d0726f2731354f1742078fbe5c Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 19:05:13 +0530 Subject: [PATCH 44/57] Update configuration-directories.md (#4831) Edits are done. Signed-off-by: ArooshLele --- docs/user-guide/configuration-directories.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/configuration-directories.md b/docs/user-guide/configuration-directories.md index 660dfec551..3893ac704b 100644 --- a/docs/user-guide/configuration-directories.md +++ b/docs/user-guide/configuration-directories.md @@ -1,7 +1,7 @@ -# Configuration Directories -When running, the App Server will access the server's settings and read or modify the contents of its resource storage. All of this data is stored within a hierarchy of folders which correspond to scopes: +# Configuration directories +When running, the App Server accesses the server's settings and reads or modifies the contents of the server's resource storage. All this data is stored within a hierarchy of folders which correspond to the following scopes: -- Product: The contents of this folder are not meant to be modified, but used as defaults for a product. +- Product: The contents of this folder are not meant to be modified, but the contents are used as defaults for a product. - Site: The contents of this folder are intended to be shared across multiple App Server instances, perhaps on a network drive. - Instance: This folder represents the broadest scope of data within the given App Server instance. - Group: Multiple users can be associated into one group, so that settings are shared among them. From 0c583bc73235b1fdeb15d6002d552e6c07abf7d1 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 19:13:50 +0530 Subject: [PATCH 45/57] Update logging-configuration.md (#4832) Variables are enclosed in backticks. Signed-off-by: ArooshLele --- docs/user-guide/logging-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/logging-configuration.md b/docs/user-guide/logging-configuration.md index 6cfa47414f..b6705fcaa9 100644 --- a/docs/user-guide/logging-configuration.md +++ b/docs/user-guide/logging-configuration.md @@ -4,7 +4,7 @@ For more information, see [Logging Utility](../extend/extend-desktop/mvd-logutil ## 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). +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: @@ -35,7 +35,7 @@ The app-server and zss will create log files containing processing messages and ### 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. +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 From 4ffa795334e8565ff4cae681ecb06e4929789842 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 19:19:29 +0530 Subject: [PATCH 46/57] Update configuring-the-framework-as-a-mediation-layer-client.md (#4833) Edits Signed-off-by: ArooshLele --- .../configuring-the-framework-as-a-mediation-layer-client.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md b/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md index 57f2b6597d..72a30ad277 100644 --- a/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md +++ b/docs/user-guide/configuring-the-framework-as-a-mediation-layer-client.md @@ -1,5 +1,5 @@ # 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, 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. +The App-server and ZSS automatically register to the API Mediation Layer when present. +If this is not desired, registration can be disabled by setting the properties `components.app-server.mediationLayer.server.enabled` to `false` for app-server and `components.zss.mediationLayer.enabled` to `false` for ZSS. From 00491e40a9211166fb067fa72d723da4caaa54b7 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 19:53:46 +0530 Subject: [PATCH 47/57] Update controlling-access-to-apps.md (#4834) Edits Signed-off-by: ArooshLele --- docs/user-guide/controlling-access-to-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/controlling-access-to-apps.md b/docs/user-guide/controlling-access-to-apps.md index c0b903ce5f..763a994f80 100644 --- a/docs/user-guide/controlling-access-to-apps.md +++ b/docs/user-guide/controlling-access-to-apps.md @@ -4,7 +4,7 @@ You can control which apps are accessible (visible) to all Zowe desktop users, a 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. -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. +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 and 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. ## Enabling RBAC From 8289f2c4b5f2eceae4c39dc3fba9fe35886ba939 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 20:03:59 +0530 Subject: [PATCH 48/57] Update controlling-access-to-dataservices.md Signed-off-by: ArooshLele --- docs/user-guide/controlling-access-to-dataservices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/controlling-access-to-dataservices.md b/docs/user-guide/controlling-access-to-dataservices.md index 7ea95347df..f80e724b42 100644 --- a/docs/user-guide/controlling-access-to-dataservices.md +++ b/docs/user-guide/controlling-access-to-dataservices.md @@ -46,5 +46,5 @@ The following are recommended for basic authorization: ## Endpoint URL length limitations SAF profiles cannot contain more than 246 characters. If the path section of an endpoint URL is long enough that the profile name exceeds the limit, the path is trimmed to only include elements that do not exceed the limit. To avoid this issue, we recommend that application developers maintain relatively short endpoint URL paths. -For information on endpoint URLs, see [Using dataservices with RBAC](../extend/extend-desktop/mvd-dataservices.md#using-dataservices-with-rbac) +For information on endpoint URLs, see [Using dataservices with RBAC](../extend/extend-desktop/mvd-dataservices.md#using-dataservices-with-rbac). From fc385ce5314056c4ae49c66f106033641673efa3 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 20:18:04 +0530 Subject: [PATCH 49/57] Update managing-cluster-mode-for-app-server.md (#4835) Edits Signed-off-by: ArooshLele --- docs/user-guide/managing-cluster-mode-for-app-server.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/managing-cluster-mode-for-app-server.md b/docs/user-guide/managing-cluster-mode-for-app-server.md index f5c6c56834..60bb107dbf 100644 --- a/docs/user-guide/managing-cluster-mode-for-app-server.md +++ b/docs/user-guide/managing-cluster-mode-for-app-server.md @@ -1,8 +1,8 @@ # Managing Cluster Mode for app-server -On the Zowe servers, the component "app-server" has an environment variable "ZLUX_NO_CLUSTER" which controls whether or not it uses cluster mode. Cluster mode is enabled by default. However, you might need to disable cluster mode under certain circumstances. When cluster mode is disabled, make sure you are aware of the potential drawbacks and benefit. +On the Zowe servers, the component app-server has an environment variable `ZLUX_NO_CLUSTER` which controls whether or not it uses cluster mode. Cluster mode is enabled by default. However, you might need to disable cluster mode under certain circumstances. When cluster mode is disabled, make sure you are aware of the potential drawbacks and benefit. -When you **disable** cluster mode, you will lose the following benefits: +When you **disable** cluster mode, you lose the following benefits: 1. **Performance under high user Count:** This is due to the absence of redundant workers, which can impact the system's efficiency when dealing with a large number of users. From 9b8cdec6ff9f57aee0b273d5228961f8e0fca3e7 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 20:42:28 +0530 Subject: [PATCH 50/57] Update zss-configuration-1.md (#4837) Edits. Signed-off-by: ArooshLele --- docs/user-guide/zss-configuration-1.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/user-guide/zss-configuration-1.md b/docs/user-guide/zss-configuration-1.md index cf629b9ce8..8f1f6e449e 100644 --- a/docs/user-guide/zss-configuration-1.md +++ b/docs/user-guide/zss-configuration-1.md @@ -1,15 +1,15 @@ # ZSS configuration -ZSS provides APIs that any server or client can use. By default, the Zowe Desktop includes Apps which rely upon ZSS APIs, and therefore it's recommended that whenever the `app-server` is enabled in the Zowe YAML, that `zss` is also enabled. +ZSS provides APIs that any server or client can use. By default, the Zowe Desktop includes apps which rely upon ZSS APIs. Therefore, it is recommended that whenever the `app-server` is enabled in the Zowe YAML file, that `zss` is also enabled. ## ZSS 64 or 31 bit modes -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. +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 plug-in's support. Official Zowe distributions contain plug-ins that support both 64 bit and 31 bit, but extensions may only support one or the other. ### Verifying which ZSS mode is in use -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: +You can check which version of ZSS you are running by looking at the log files. At startup, the message ZWES1013I states which mode is being used, for example: `ZWES1013I ZSS Server has started. Version 3.0.0 64-bit` @@ -17,13 +17,13 @@ Or `ZWES1013I ZSS Server has started. Version 3.0.0 31-bit` -### Verifying which ZSS mode plugins support +### Verifying which ZSS mode plug-ins 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. +You can check if a ZSS plug-in supports 64 bit or 31 bit ZSS by reading the pluginDefinition.json file of the plug-in. +In each component or extension you have, its manifest file will state if there are `appFw` plug-in 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. +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 plug-in only supports 31 bit ZSS. A plug-in 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) From e94ac302325b06f4255b046b15c2e914c8efffcd Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 20:42:53 +0530 Subject: [PATCH 51/57] Update using-multiple-zis-instances.md (#4836) Edits Signed-off-by: ArooshLele --- docs/user-guide/using-multiple-zis-instances.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/using-multiple-zis-instances.md b/docs/user-guide/using-multiple-zis-instances.md index 5b058b829e..b807620f83 100644 --- a/docs/user-guide/using-multiple-zis-instances.md +++ b/docs/user-guide/using-multiple-zis-instances.md @@ -1,7 +1,7 @@ # 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. +When you install Zowe, it is ready to be used for one instance of each component. However, ZIS can have a one-to-many relationship with the Zowe webservers, and so you can have more than one copy of ZIS for testing or to handle different groups of ZIS plugins. -The following steps can be followed to point a Zowe instance at a particular ZIS server. +Use the following steps to point a Zowe instance at a particular ZIS server: 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. From bf3503c2717cc9a40459c57a5ac621699526c89e Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 20:46:52 +0530 Subject: [PATCH 52/57] Update zss-configuration-1.md (#4838) Signed-off-by: ArooshLele --- docs/user-guide/zss-configuration-1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/zss-configuration-1.md b/docs/user-guide/zss-configuration-1.md index 8f1f6e449e..6590a39d96 100644 --- a/docs/user-guide/zss-configuration-1.md +++ b/docs/user-guide/zss-configuration-1.md @@ -19,9 +19,9 @@ Or ### Verifying which ZSS mode plug-ins support -You can check if a ZSS plug-in supports 64 bit or 31 bit ZSS by reading the pluginDefinition.json file of the plug-in. +You can check if a ZSS plug-in supports 64 bit or 31 bit ZSS by reading the `pluginDefinition.json` file of the plug-in. In each component or extension you have, its manifest file will state if there are `appFw` plug-in entries. -In each folder referenced by the `appFw` section, you will see a pluginDefinition.json file. +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 plug-in only supports 31 bit ZSS. A plug-in only supporting 31 bit ZSS must be recompiled for 64 bit support, so you must contact the developers to accomplish that. From f68e425a92c2188616a9b239a4589c165194f8e1 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Mon, 15 Dec 2025 20:50:09 +0530 Subject: [PATCH 53/57] Update zss-configuration-1.md (#4839) Edits Signed-off-by: ArooshLele --- docs/user-guide/zss-configuration-1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/zss-configuration-1.md b/docs/user-guide/zss-configuration-1.md index 6590a39d96..d422bae13c 100644 --- a/docs/user-guide/zss-configuration-1.md +++ b/docs/user-guide/zss-configuration-1.md @@ -35,9 +35,9 @@ You can switch between ZSS 64 bit and 31 bit mode by setting the value `componen In a standard Zowe installation, all Zowe servers utilize the API Mediation Layer's token-based, single-sign on authentication. This authentication in turn cooperates with z/OSMF, and the session duration is typically that of z/OSMF's, which defaults to 8 hours before the session expires. In that situation, customization of session duration is best done by customizing z/OSMF's session duration, as a part of its Liberty configuration. -If you are not using the API Mediation Layer, or are trying to contact ZSS directly, then ZSS's own session logic is used. When authenticated directly to ZSS, it will respond to authenticated HTTP requests with a cookie which is valid by default for 1 hour. This can be customized by creating and editing a file named "timeouts.json" within ZSS's instance directory. The default location is `/app-server/serverConfig/timeouts.json`, because the default instance directory is `/app-server`, but can be customized by editing the value of `components.zss.instanceDir`. +If you are not using the API Mediation Layer, or are trying to contact ZSS directly, then ZSS's own session logic is used. When authenticated directly to ZSS, it will respond to authenticated HTTP requests with a cookie which is valid by default for 1 hour. This can be customized by creating and editing a file named `timeouts.json` within ZSS's instance directory. The default location is `/app-server/serverConfig/timeouts.json`, because the default instance directory is `/app-server`, but can be customized by editing the value of `components.zss.instanceDir`. -The timeouts.json file has the following layout: +The `timeouts.json` file has the following layout: ``` { From 41661ff7e9804f4076801336f7b6f8887fc657fe Mon Sep 17 00:00:00 2001 From: arooshlele Date: Tue, 16 Dec 2025 15:41:30 +0530 Subject: [PATCH 54/57] Updating network-configuration.md Signed-off-by: arooshlele --- docs/user-guide/network-configuration.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/network-configuration.md b/docs/user-guide/network-configuration.md index 295fafbfd1..1e3e43fd8c 100644 --- a/docs/user-guide/network-configuration.md +++ b/docs/user-guide/network-configuration.md @@ -1,8 +1,10 @@ # Network configuration -**Note:** The following attributes are to be defined in the Zowe configuration file. +:::note Note +The following attributes are to be defined in the Zowe configuration file. The App Server and ZSS both can be accessed over HTTPS, either natively or via AT-TLS by setting appropriate AT-TLS rules and Zowe YAML assignments. When using native HTTPS, the TLS properties can be further customized within the YAML. +::: ## Port configuration From 30b53c6592505a3be965a0ece95d1aaaf8daa934 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Tue, 16 Dec 2025 15:54:07 +0530 Subject: [PATCH 55/57] Update administering-the-servers-and-plugins-using-an-api.md (#4844) The Docsaurus syntax is applied on the note. Signed-off-by: ArooshLele --- .../administering-the-servers-and-plugins-using-an-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md b/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md index 8127627877..c0ba86b39e 100644 --- a/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md +++ b/docs/user-guide/administering-the-servers-and-plugins-using-an-api.md @@ -23,6 +23,6 @@ The API returns the following information in a JSON response: Swagger API documentation is provided in the `/components/app-server/share/zlux-app-server/doc/swagger/server-plugins-api.yaml` file. To see it in HTML format, you can paste the contents into the Swagger editor at https://editor.swagger.io/. -**Note:** The "agent" end points interact with the agent specified in the zowe configuration file. By default this is ZSS. - - +:::note Note +The "agent" end points interact with the agent specified in the zowe configuration file. By default this is ZSS. +::: From e4f0a23e884f160a3c031b3b3e565045350a7341 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Tue, 16 Dec 2025 15:56:56 +0530 Subject: [PATCH 56/57] Update controlling-access-to-apps.md (#4845) Signed-off-by: ArooshLele --- docs/user-guide/controlling-access-to-apps.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/controlling-access-to-apps.md b/docs/user-guide/controlling-access-to-apps.md index 763a994f80..7bc03405eb 100644 --- a/docs/user-guide/controlling-access-to-apps.md +++ b/docs/user-guide/controlling-access-to-apps.md @@ -14,8 +14,9 @@ By default, RBAC is disabled and all authenticated Zowe users can access all dat ## Controlling app access for all users -**Note:** +:::note Note - `` variable comes from the Zowe configuration file. +::: 1. Enable RBAC. From 1708583e90aab11f87d0b827786dda2dd30e6ef3 Mon Sep 17 00:00:00 2001 From: ArooshLele Date: Tue, 16 Dec 2025 16:00:06 +0530 Subject: [PATCH 57/57] Update controlling-access-to-apps.md (#4846) The Note is now as per Docasaurus's syntax. Signed-off-by: ArooshLele --- docs/user-guide/controlling-access-to-apps.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/controlling-access-to-apps.md b/docs/user-guide/controlling-access-to-apps.md index 7bc03405eb..90ed86b1fa 100644 --- a/docs/user-guide/controlling-access-to-apps.md +++ b/docs/user-guide/controlling-access-to-apps.md @@ -66,9 +66,10 @@ By default, RBAC is disabled and all authenticated Zowe users can access all dat } ``` - **Notes:** + :::note Note - Identifier and version attributes are required. - When a user logs in to the desktop, Zowe determines which apps they can see by concatenating the list of apps available to all users with the apps available to the individual user. +::: 6. [Restart the app server](start-zowe-zos.md).