Dividing mvd-configuration.md file into smaller topics

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://<zowe.externalDomain>:<components.gateway.port>/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 API ML is not used, you can access ZSS directly at `https://<zowe.externalDomain>:<components.zss.port>/`.
+

docs/user-guide/administering-the-servers-and-plugins-using-an-api.md

@@ -0,0 +1,28 @@
+# 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)                                             | 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)                                       | 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 `<zowe.runtimeDirectory>/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 Note
+The "agent" end points interact with the agent specified in the zowe configuration file. By default this is ZSS.
+:::

docs/user-guide/app-plugin-configuration.md

@@ -0,0 +1,4 @@
+# App plug-in configuration
+
+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 `<workspaceDirectory>/app-server/plugins` folder. This location can be customized with the `components.app-server.pluginsDir` variable in the Zowe configuration file.
+

docs/user-guide/configuration-directories.md

@@ -0,0 +1,12 @@
+# 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 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.
+- 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)
+
+

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. 
+
+

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 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.
+

docs/user-guide/controlling-access-to-apps.md

@@ -0,0 +1,76 @@
+# 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 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
+
+By default, RBAC is disabled and all authenticated Zowe users can access all dataservices. To enable RBAC, follow these steps:
+
+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
+
+:::note Note
+- `<zowe.runtimeDirectory>` variable comes from the Zowe configuration file.
+:::
+
+1. Enable RBAC.
+
+2. Navigate to the following location:
+   ```
+   <zowe.runtimeDirectory>/components/app-server/share/zlux-app-server/defaults/ZLUX/pluginStorage/org.zowe.zlux.bootstrap/plugins
+   ```
+3. Copy the `allowedPlugins.json` file and paste the file in the following location:
+   ```
+   <zowe.workspaceDirectory>/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 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).
+
+## 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:
+    ```
+    <zowe.workspaceDirectory>/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:
+   ```
+   <zpwe.runtimeDirectory>/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 a user can access. For example:
+    ```json
+    {
+      "allowedPlugins": [
+        {
+          "identifier": "org.zowe.appA",
+          "versions": [
+            "1.1"
+          ]
+        },
+        {
+          "identifier": "org.zowe.appB",
+          "versions": [
+            "*"
+          ]
+        },
+    }
+    ```
+
+    :::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).
+
+

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 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.
+
+Endpoints are identified by URIs in the following format:
+
+`/ZLUX/plugins/<plugin_id>/services/<service>/<version>/<path>`
+
+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.<zowe.rbacProfileIdentifier>.<servicename>.<pluginid_with_underscores>.<service>.<HTTP_method>.<url_with_forward_slashes_replaced_by_periods>`
+
+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 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).
+

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 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.
+
+In the Desktop, Apps that you opened prior to expiration will remain open so that your work can resume after entering new credentials.
+
+

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:
+
+```yaml
+components:
+  app-server:
+    logLevels:
+      _zsf.routing: 0
+      _zsf.install: 0
+```
+
+```yaml
+components:
+  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: `<zowe.logDirectory>/appServer-yyyy-mm-dd-hh-mm.log`
+- ZSS: `<zowe.logDirectory>/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).
+
+