Skip to content

Configuration for ZLUX App Server & ZSS

Jump to bottom Edit New page
1000TurquoisePogs edited this page Nov 8, 2023 · 14 revisions

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

The servers use a YAML file for configuration. The global schema describes the parts of configuration that are common between servers, while the App Server specifically is configured by the components.app-server section of the YAML, and that section follows this App-server schema The App server can additionally use CLI arguments or environment variables to override the YAML file.

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

Directories example

// All paths relative to zlux-app-server/lib
// In real installations, these values will be configured during the install.
  "productDir":"../defaults",
  "siteDir":"/home/myuser/.zowe/workspace/app-server/site",
  "instanceDir":"/home/myuser/.zowe/workspace/app-server",
  "groupsDir":"/home/myuser/.zowe/workspace/app-server/groups",
  "usersDir":"/home/myuser/.zowe/workspace/app-server/users",

CLI arguments

CLI arguments take precedence over environment variable and configuration file. 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 attribute, so to set the value of a nested object, such as the https configuration, you need multiple period-separated values. For example, to get:

components:
  app-server:
    node:
      https:
        ipAddresses:
        - "0.0.0.0"
        port: 8554
        keys:
        - "../defaults/serverConfig/server.key"
        certificates:
        - "../defaults/serverConfig/server.cert"

In CLI argument format you would need to specify:

node.https.ipAddresses="0.0.0.0",
node.https.port=8554
node.https.keys="../defaults/serverConfig/server.key",
node.https.certificates="../defaults/serverConfig/server.cert",

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.

Environment variables

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 JSON object attribute, so to set the value of a nested object, such as the https configuration, you need multiple values. For example, to get:

components:
  app-server:
    node:
      https:
        ipAddresses:
        - "0.0.0.0"
        port: 8554
        keys:
        - "../defaults/serverConfig/server.key"
        certificates:
        - "../defaults/serverConfig/server.cert"
    logLevels:
    - _zsf.auth: 1
    - org.zowe.terminal.tn3270.*: 5

In Environment variable format you would need to specify:

ZWED_node_https_ipAddresses="0.0.0.0",
ZWED_node_https_port=8554
ZWED_node_https_keys="../defaults/serverConfig/server.key",
ZWED_node_https_certificates="../defaults/serverConfig/server.cert",
ZWED_logLevels__x5fzsf____auth:"1",
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 .

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.

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

Plugins directory example

// All paths relative to zlux-app-server/lib
// In real installations, these values will be configured during the install.
//...
  "pluginsDir":"../defaults/plugins",

Logging configuration

See logger documentation

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. More information about the configuration can be found In its README.

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

Desktop Timeout configuration

It is possible to configure custom App server session timeout values at the user and group level. This can be done via a timeouts.json file in $INSTANCE_DIR/workspace/app-server/serverConfig/timeouts.json.

{
 "users": {
    "xxxx": 400,
    "xxxx2": -1
  },
  "groups": {
    "group1": 200,
  }
}

The values specified for users and groups set the timeout period in seconds. In the example above, the timeout period for user xxxx would be 400 seconds. To set an unlimited (non-expiring) session, specify a value of -1. In the example, user xxxx2 will have a non-expiring session.

Add a custom footer
Add a custom sidebar
Clone this wiki locally