From 84255ed66fe6052e6d5b700199895d4e2cd517af Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Wed, 8 Nov 2023 06:11:42 -0500 Subject: [PATCH 1/5] Update mvd-server-config.md Signed-off-by: 1000TurquoisePogs --- .../extend-desktop/mvd-server-config.md | 43 ++++++------------- 1 file changed, 14 insertions(+), 29 deletions(-) diff --git a/docs/extend/extend-desktop/mvd-server-config.md b/docs/extend/extend-desktop/mvd-server-config.md index bc9a67423e..65e2ddb774 100644 --- a/docs/extend/extend-desktop/mvd-server-config.md +++ b/docs/extend/extend-desktop/mvd-server-config.md @@ -1,15 +1,17 @@ The Zowe's App Server and ZSS rely on many required or optional parameters to run, which includes setting up networking, deployment directories, plugin locations, and more. -These parameters can be specified in multiple ways: configuration files, CLI arguments, or environment variables. -Every configuration option and requirement is documented within the application framework [json-schema file](https://github.com/zowe/zlux/blob/v2.x/staging/schemas/zlux-config-schema.json) -# Configuration file -In Zowe's server configuration file, app-server parameters can be specified within `components.app-server` as shown in the component [json-schema file](https://github.com/zowe/zlux/blob/v2.x/staging/schemas/zowe-schema.json), or `components.zss` for ZSS. +# Configuration File +The servers use a YAML file for configuration. The [global schema](https://github.com/zowe/zowe-install-packaging/blob/v2.x/staging/schemas/zowe-yaml-schema.json) describes the parts of configuration that are common between servers. +The App Server specifically is configured by the `components.app-server` section of the YAML, and that section follows [this App-server schema](https://github.com/zowe/zlux-app-server/blob/v2.x/staging/schemas/app-server-config.json) +ZSS is instead configured by the `components.zss` section, following [the ZSS schema](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json) +The App server can additionally use CLI arguments or environment variables to override the YAML file. -# Environment variables +# Environment variables (app-server only) CLI arguments take precedence over the configuration file, but are overridden by the CLI arguments. The format is `ZWED_key=value`, where "ZWED_" is a prefix for any configuration object. -The key maps to a YAML object attribute, so to set the value of a nested object, such as the https configuration, you need multiple values. +The attributes specified will be put within the `components.app-server` subsection of the Zowe configuration. +The key maps to a JSON object attribute, so to set the value of a nested object, such as the https configuration, you need multiple values. For example: ``` node: @@ -54,16 +56,9 @@ ZWED_logLevels_org____zowe____terminal____tn3270_x2e_x2a:5 * strings can have quotes, but otherwise everything that isnt an array, boolean, or number is a string * objects are never values. They are the keys. -## Friendly names for environment variables -Some common configuration options have names that do not follow the above special syntax. These options get mapped to the special syntax when the server runs, so the same behavior can be configured in more than one way. Many of these values are listed here https://docs.zowe.org/stable/user-guide/configure-zowe-zosmf-workflow/#configure-the-zowe-instance-directory but for the App Server, the code that maps these values is contained within https://github.com/zowe/zlux-app-server/blob/v2.x/master/bin/convert-env.sh - - -Although overridden by both environment variables and CLI arguments, for convenience the App server and ZSS read from a configuration file with a common structure. ZSS reads this directly as a startup argument, while the App Server as defined in the [zlux-server-framework](https://github.com/zowe/zlux-server-framework) repository accepts several parameters which are intended to be read from a YAML file through an implementer of the server, such the default provided in the [zlux-app-server](https://github.com/zowe/zlux-app-server) repository, namely the [lib/zluxServer.js](https://github.com/zowe/zlux-app-server/blob/v2.x/master/lib/zluxServer.js) file. This file accepts a YAML file that specifies most if not all parameters needed, but some other parameters can be provided via flags if desired. - - # CLI arguments (app-server only) CLI arguments take precedence over environment variable and configuration files. -The format is `--key=value` +The format is `--key=value` and the attributes specified will be put within the `components.app-server` subsection of the Zowe configuration. The key maps to a YAML object attribute, so to set the value of a nested object, such as the https configuration, you need multiple period-separated values. For example: ``` @@ -86,7 +81,7 @@ node.https.certificates="../defaults/serverConfig/server.cert" **NOTE: ZSS does not support CLI arguments** -**The key name is case-sensitive.** +**The key names are case-sensitive.** **The types of the values are syntax-sensitive.** * Numbers are treated as numbers, not strings. @@ -142,18 +137,8 @@ To include Apps, be sure to define the location of the Plugins directory in the For more information, see [Logging Utility](mvd-logutility.md). ## ZSS Configuration -When running ZSS, it will require a configuration file similar or the same as the one used for the App Server. The attributes that are needed for ZSS, at minimum, are: *productDir*, *siteDir*, *instanceDir*, *groupsDir*, *usersDir*, *pluginsDir* and **agent**. All of these attributes have the same meaning as described above for the App server, but if the App server and ZSS are not run from the same location, then these directories may be different if desired. - -### ZSS Networking - -The attributes that control ZSS exclusively are within the **agent** object. ZSS uses HTTPS by default, but for those who wish to use AT-TLS instead of the built-in HTTPS support, ZSS can use HTTP as well. HTTP should never be used without [AT-TLS](../../user-guide/mvd-configuration#defining-the-at-tls-rule), as this is a security risk. The values `agent.https.port`, `agent.http.port` tell ZSS which ports to bind to, but also where the app-server can find ZSS. The values `agent.host` is used to tell app-server where to find ZSS as well, though `agent.https.ipAddresses` and `agent.http.ipAddresses` tell ZSS which addresses to bind to. For addresses, at this time only the first value of that array is used, and it may either be a hostname or an ipv4 address. +ZSS is configured by the same Zowe YAML file used by the App server, within the `components.zss` section of the file. The [ZSS schema for components.zss be found here](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json). More information about the configuration can be found [In its README](https://github.com/zowe/zss/#quick-run-how-to-start-zss). -Example of the agent body: -``` - agent: - host: localhost - https: - ipAddresses: 0.0.0.0 - port: 7557 - -``` +### Connecting ZSS to App Server +The App Server can connect to ZSS either directly or through the API Mediation Layer Gateway when that is running. +The connection information is stored within the object `components.app-server.agent`, which describes whether the Gateway is involved, or if not, on which host and port can ZSS be found. For more information, see the [agent section of the schema](https://github.com/zowe/zlux-app-server/blob/c22105381e129bd999c47e838b424679eba26aa6/schemas/app-server-config.json#L262) From 88e9ca6cb9fe6b3db07595dc669e4b5c7f7bdaa0 Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Wed, 8 Nov 2023 06:22:53 -0500 Subject: [PATCH 2/5] Update mvd-logutility.md link to mvd-server-config.md Signed-off-by: 1000TurquoisePogs --- docs/extend/extend-desktop/mvd-logutility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/extend-desktop/mvd-logutility.md b/docs/extend/extend-desktop/mvd-logutility.md index 82f6a9bcc0..babe67e508 100644 --- a/docs/extend/extend-desktop/mvd-logutility.md +++ b/docs/extend/extend-desktop/mvd-logutility.md @@ -124,7 +124,7 @@ The application plug-in framework provides ways to specify what component logger #### Server startup logging configuration -[The server configuration file](https://github.com/zowe/zlux/wiki/Configuration-for-zLUX-App-Server-&-ZSS) allows for specification of default log levels, as a top-level attribute `logLevel`, which takes key-value pairs where the key is a regex pattern for component IDs, and the value is an integer for the log levels. +[The server configuration file](mvd-server-config.md) allows for specification of default log levels, as a top-level attribute `logLevel`, which takes key-value pairs where the key is a regex pattern for component IDs, and the value is an integer for the log levels. For example: ``` From 9e73f2a3ab331e5f940619ea5da6dc45b588d0e5 Mon Sep 17 00:00:00 2001 From: anaxceron Date: Fri, 12 Jan 2024 15:06:36 -0500 Subject: [PATCH 3/5] fixed punctuation, style, formatting Signed-off-by: anaxceron --- docs/extend/extend-desktop/mvd-logutility.md | 29 ++----- .../extend-desktop/mvd-server-config.md | 84 ++++++++++++------- 2 files changed, 63 insertions(+), 50 deletions(-) diff --git a/docs/extend/extend-desktop/mvd-logutility.md b/docs/extend/extend-desktop/mvd-logutility.md index babe67e508..64c0dd327c 100644 --- a/docs/extend/extend-desktop/mvd-logutility.md +++ b/docs/extend/extend-desktop/mvd-logutility.md @@ -2,24 +2,6 @@ The `zlux-shared` repository provides a logging utility for use by dataservices and web content for an application plug-in. -1. [Logging Objects](#logging-objects) -1. [Logger IDs](#logger-ids) -1. [Accessing Logger Objects](#accessing-logger-objects) - 1. [Logger](#logger) - 1. [App Server](#app-server) - 1. [Web](#web) - 1. [Component Logger](#component-logger) - 1. [App Server](#app-server-1) - 1. [Web](#web-1) -1. [Logger API](#logger-api) -1. [Component Logger API](#component-logger-api) -1. [Log Levels](#log-levels) -1. [Logging Verbosity](#logging-verbosity) - 1. [Configuring Logging Verbosity](#configuring-logging-verbosity) - 1. [Server Startup Logging Configuration](#server-startup-logging-configuration) -1. [Using log message IDs](#using-log-message-ids) - - ## Logging objects The logging utility is based on the following objects: @@ -58,7 +40,6 @@ Component loggers are created from the core logger object, but when working with See **Router Dataservice Context** in the topic [Dataservices](mvd-dataservices.md). - ## Logger API The following constants and functions are available on the central logging object. @@ -106,8 +87,11 @@ An enum, `LogLevel`, exists for specifying the verbosity level of a logger. The | FINER | 4 | TRACE | 5 -**Note:** The default log level for a logger is **INFO**. +:::note + +The default log level for a logger is **INFO**. +::: ## Logging verbosity @@ -127,6 +111,7 @@ The application plug-in framework provides ways to specify what component logger [The server configuration file](mvd-server-config.md) allows for specification of default log levels, as a top-level attribute `logLevel`, which takes key-value pairs where the key is a regex pattern for component IDs, and the value is an integer for the log levels. For example: + ``` "logLevel": { "com.rs.configjs.data.access": 2, @@ -139,9 +124,11 @@ For example: //"_unp.dsauth": 2 }, ``` + For more information about the server configuration file, see [Zowe Application Framework (zLUX) configuration](../../user-guide/mvd-configuration#configuration-file). ## Using log message IDs + To make technical support for your application easier, create IDs for common log messages and use substitution to generate them. When you use IDs, people fielding support calls can identify and solve problems more quickly. IDs are particularly helpful if your application is translated, because it avoids users having to explain problems using language that the tech support person might not understand. To use log message IDs, take the following steps: @@ -179,7 +166,7 @@ To use log message IDs, take the following steps: ``` DATE TIME:TIME:TIME.TIME username INFO (org.zowe.app.name,:) A001 - Приложение создано. ``` - + ### Message ID logging examples Server core: https://github.com/zowe/zlux-server-framework/blob/v2.x/master/plugins/config/lib/assets/i18n/log/messages_en.json diff --git a/docs/extend/extend-desktop/mvd-server-config.md b/docs/extend/extend-desktop/mvd-server-config.md index 65e2ddb774..03b8ebca59 100644 --- a/docs/extend/extend-desktop/mvd-server-config.md +++ b/docs/extend/extend-desktop/mvd-server-config.md @@ -1,17 +1,24 @@ The Zowe's App Server and ZSS rely on many required or optional parameters to run, which includes setting up networking, deployment directories, plugin locations, and more. +# Configuration file -# Configuration File The servers use a YAML file for configuration. The [global schema](https://github.com/zowe/zowe-install-packaging/blob/v2.x/staging/schemas/zowe-yaml-schema.json) describes the parts of configuration that are common between servers. -The App Server specifically is configured by the `components.app-server` section of the YAML, and that section follows [this App-server schema](https://github.com/zowe/zlux-app-server/blob/v2.x/staging/schemas/app-server-config.json) -ZSS is instead configured by the `components.zss` section, following [the ZSS schema](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json) + +The App Server specifically is configured by the `components.app-server` section of the YAML, and that section follows [this App-server schema](https://github.com/zowe/zlux-app-server/blob/v2.x/staging/schemas/app-server-config.json). + +ZSS is instead configured by the `components.zss` section, following [the ZSS schema](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json). + The App server can additionally use CLI arguments or environment variables to override the YAML file. # Environment variables (app-server only) + CLI arguments take precedence over the configuration file, but are overridden by the CLI arguments. -The format is `ZWED_key=value`, where "ZWED_" is a prefix for any configuration object. +The format is `ZWED_key=value`, where `WED_` is a prefix for any configuration object. + The attributes specified will be put within the `components.app-server` subsection of the Zowe configuration. + The key maps to a JSON object attribute, so to set the value of a nested object, such as the https configuration, you need multiple values. + For example: ``` node: @@ -39,27 +46,31 @@ ZWED_logLevels_org____zowe____terminal____tn3270_x2e_x2a:5 ``` **The key names are syntax sensitive.** -* They are case-sensitive -* All ascii characters except " are allowed in the object attribute names. - * An encoding scheme is used for many symbols because environment variables can only have names with the characters A-Z, a-z, 0-9, `_`, `.`, and `-` - * The scheme is _x followed by 2 hex numbers will be converted to the corresponding ASCII character, such as _x41 mapping to `A` -* _ is used as the object separator, so an escape sequence is used if `_` is actually needed for the key. - * Single leading and trailing _ are treated as literal `_` - * __ will be maps to literal `_` - * ___ maps to literal `-` - * ____ maps to literal `.` +* They are case-sensitive. +* All ASCII characters except `"` are allowed in the object attribute names. + * An encoding scheme is used for many symbols because environment variables can only have names with the characters `A`-`Z`, `a`-`z`, `0`-`9`, `_`, `.`, and `-`. + * The scheme is _x followed by 2 hex numbers will be converted to the corresponding ASCII character, such as _x41 mapping to `A`. +* `_` is used as the object separator, so an escape sequence is used if `_` is actually needed for the key. + * Single leading and trailing _ are treated as literal `_`. + * `__` will be maps to literal `_` + * `___` maps to literal `-` + * `____` maps to literal `.` **The types of the values are syntax-sensitive.** * Numbers are treated as numbers, not strings. -* false & true are treated as boolean. -* commas are for arrays. An array of length 1 has a comma at the end -* strings can have quotes, but otherwise everything that isnt an array, boolean, or number is a string -* objects are never values. They are the keys. +* `false` and `true` are treated as boolean. +* Commas are for arrays. An array of length 1 has a comma at the end. +* Strings can have quotes, but otherwise everything that is not an array, boolean, or number is a string. +* Objects are never values, they are the keys. # CLI arguments (app-server only) + CLI arguments take precedence over environment variable and configuration files. + The format is `--key=value` and the attributes specified will be put within the `components.app-server` subsection of the Zowe configuration. + The key maps to a YAML object attribute, so to set the value of a nested object, such as the https configuration, you need multiple period-separated values. + For example: ``` node: @@ -79,24 +90,30 @@ node.https.keys="../defaults/serverConfig/server.key" node.https.certificates="../defaults/serverConfig/server.cert" ``` -**NOTE: ZSS does not support CLI arguments** +:::note + +ZSS does not support CLI arguments. + +::: **The key names are case-sensitive.** **The types of the values are syntax-sensitive.** * Numbers are treated as numbers, not strings. -* false & true are treated as boolean. -* commas are for arrays. An array of length 1 has a comma at the end -* strings can have quotes, but otherwise everything that isnt an array, boolean, or number is a string -* objects are never values. They are the keys. - +* `false` and `true` are treated as boolean. +* Commas are for arrays. An array of length 1 has a comma at the end. +* Strings can have quotes, but otherwise everything that is not an array, boolean, or number is a string. +* Objects are never values, they are the keys. # Parameter Details + Below is some more detail on certain parameters than can be covered within the json-schema. ## Configuration Directories + When running, the App Server will access the server's settings and read/modify the contents of its resource storage. -All of this data is stored within a heirarchy of a few folders, which is correspond to scopes: + +All of this data is stored within a hierarchy of a few folders, which is 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. @@ -106,25 +123,31 @@ All of this data is stored within a heirarchy of a few folders, which is corresp These directories dictate where the [Configuration Dataservice](https://github.com/zowe/zlux/wiki/Configuration-Dataservice) will store content. ### Directories example + ``` "productDir":"../defaults", "siteDir":"/home/myuser/.zowe/workspace/app-server/site", "instanceDir":"/home/myuser/.zowe/workspace/app-server", "groupsDir":"/home/myuser/.zowe/workspace/app-server/groups", "usersDir":"/home/myuser/.zowe/workspace/app-server/users", - ``` - ## App configuration + This section does not cover any dynamic runtime inclusion of Apps, but rather Apps defined in advance. + In the configuration file, a directory can be specified which contains JSON files which tell the server what App is to be included and where to find it on disk. The backend of these Apps use the Server's Plugin structure, so much of the server-side references to Apps use the term Plugin. To include Apps, be sure to define the location of the Plugins directory in the configuration file, via the top-level attribute *pluginsDir* -**NOTE: In this example, the directory for these JSON files is [/defaults/plugins](https://github.com/zowe/zlux-app-server/tree/v2.x/master/defaults/plugins). Yet, in order to separate configuration files from runtime files, the App Server will initialize by copying the contents of this folder into the defined instance directory, of which the default is ~/.zowe/workspace/app-server. So, the example configuration file uses the latter directory.** +:::note + +In this example, the directory for these JSON files is [/defaults/plugins](https://github.com/zowe/zlux-app-server/tree/v2.x/master/defaults/plugins). Yet, in order to separate configuration files from runtime files, the App Server will initialize by copying the contents of this folder into the defined instance directory, of which the default is ~/.zowe/workspace/app-server. So, the example configuration file uses the latter directory. + +::: + +### Plug-ins directory example -### Plugins directory example ``` // All paths relative to zlux-app-server/lib // In real installations, these values will be configured during the install. @@ -137,8 +160,11 @@ To include Apps, be sure to define the location of the Plugins directory in the For more information, see [Logging Utility](mvd-logutility.md). ## ZSS Configuration -ZSS is configured by the same Zowe YAML file used by the App server, within the `components.zss` section of the file. The [ZSS schema for components.zss be found here](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json). More information about the configuration can be found [In its README](https://github.com/zowe/zss/#quick-run-how-to-start-zss). + +ZSS is configured by the same Zowe YAML file used by the App server, within the `components.zss` section of the file. The [ZSS schema for components.zss be found here](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json). More information about the configuration can be found in its [README file](https://github.com/zowe/zss/#quick-run-how-to-start-zss). ### Connecting ZSS to App Server + The App Server can connect to ZSS either directly or through the API Mediation Layer Gateway when that is running. + The connection information is stored within the object `components.app-server.agent`, which describes whether the Gateway is involved, or if not, on which host and port can ZSS be found. For more information, see the [agent section of the schema](https://github.com/zowe/zlux-app-server/blob/c22105381e129bd999c47e838b424679eba26aa6/schemas/app-server-config.json#L262) From 3049da6b885ae285e3bc50b97453eb17f6e59e5c Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Tue, 26 Mar 2024 10:10:02 -0400 Subject: [PATCH 4/5] Update sidebars.js Signed-off-by: 1000TurquoisePogs --- sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/sidebars.js b/sidebars.js index 5385cfb121..e050e20aba 100644 --- a/sidebars.js +++ b/sidebars.js @@ -722,6 +722,7 @@ module.exports = { type: "category", label: "Developing for Zowe Application Framework", items: [ + "extend/extend-desktop/mvd-server-config", "extend/extend-desktop/mvd-extendingzlux", "extend/extend-desktop/mvd-plugindefandstruct", "extend/extend-desktop/mvd-buildingplugins", From de3a5553829a04dd59ed1d882202bd41dde42b44 Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Fri, 27 Sep 2024 15:34:20 +0200 Subject: [PATCH 5/5] Update mvd-server-config.md with title and headers Signed-off-by: 1000TurquoisePogs --- .../extend-desktop/mvd-server-config.md | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/extend/extend-desktop/mvd-server-config.md b/docs/extend/extend-desktop/mvd-server-config.md index 8f385cd7f2..a3986037b3 100644 --- a/docs/extend/extend-desktop/mvd-server-config.md +++ b/docs/extend/extend-desktop/mvd-server-config.md @@ -1,6 +1,8 @@ +# Advanced Server Configuration + The Zowe's App Server and ZSS rely on many required or optional parameters to run, which includes setting up networking, deployment directories, plugin locations, and more. -# Configuration file +## Configuration file The servers use a YAML file for configuration. The [global schema](https://github.com/zowe/zowe-install-packaging/blob/v2.x/staging/schemas/zowe-yaml-schema.json) describes the parts of configuration that are common between servers. @@ -10,7 +12,7 @@ ZSS is instead configured by the `components.zss` section, following [the ZSS sc The App server can additionally use CLI arguments or environment variables to override the YAML file. -# Environment variables (app-server only) +## Environment variables (app-server only) CLI arguments take precedence over the configuration file, but are overridden by the CLI arguments. The format is `ZWED_key=value`, where `WED_` is a prefix for any configuration object. @@ -64,7 +66,7 @@ ZWED_logLevels_org____zowe____terminal____tn3270_x2e_x2a:5 * Objects are never values, they are the keys. -# CLI arguments (app-server only) +## CLI arguments (app-server only) CLI arguments take precedence over environment variable and configuration files. @@ -106,11 +108,11 @@ ZSS does not support CLI arguments. * Strings can have quotes, but otherwise everything that is not an array, boolean, or number is a string. * Objects are never values, they are the keys. -# Parameter Details +## Parameter Details Below is some more detail on certain parameters than can be covered within the json-schema. -## Configuration Directories +### Configuration Directories When running, the App Server will access the server's settings and read/modify the contents of its resource storage. @@ -123,7 +125,7 @@ All of this data is stored within a hierarchy of a few folders, which is corresp These directories dictate where the [Configuration Dataservice](https://github.com/zowe/zlux/wiki/Configuration-Dataservice) will store content. -### Directories example +#### Directories example ``` "productDir":"../defaults", @@ -133,7 +135,7 @@ These directories dictate where the [Configuration Dataservice](https://github.c "usersDir":"/home/myuser/.zowe/workspace/app-server/users", ``` -## App configuration +### App configuration This section does not cover any dynamic runtime inclusion of Apps, but rather Apps defined in advance. @@ -147,7 +149,7 @@ In this example, the directory for these JSON files is [/defaults/plugins](https ::: -### Plug-ins directory example +#### Plug-ins directory example ``` // All paths relative to zlux-app-server/lib @@ -156,15 +158,15 @@ In this example, the directory for these JSON files is [/defaults/plugins](https "pluginsDir":"../defaults/plugins", ``` -## Logging configuration +### Logging configuration For more information, see [Logging Utility](mvd-logutility.md). -## ZSS Configuration +### ZSS Configuration ZSS is configured by the same Zowe YAML file used by the App server, within the `components.zss` section of the file. The [ZSS schema for components.zss be found here](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json). More information about the configuration can be found in its [README file](https://github.com/zowe/zss/#quick-run-how-to-start-zss). -### Connecting ZSS to App Server +#### Connecting ZSS to App Server The App Server can connect to ZSS either directly or through the API Mediation Layer Gateway when that is running.