Step 27B(I): Configurations for the OPT_EMBEDDED_WEBSERVER Option

This topic describes the configuration steps for the OPT_EMBEDDED_WEBSERVER option. If you're using the OPT_LIBERTY_DEPLOYED option, see Step 27B(II): Configurations for the OPT_LIBERTY_DEPLOYED Option.

Set up the JCL procedure

The sample procedure ING.SINGSAMP(INGROJCL) starts the Java™ application of System Automation Operations REST Server.

You need to modify the CONFIG parameter in the sample procedure to the custom directory of your choice. For example, '/etc/ing/restsrvr/config'.

//INGROSRV PROC CONFIG='/etc/ing/restsrvr/config',
//   JAVACLS='org.springframework.boot.loader.launcher.JarLauncher',
//   LOGLVL='+I',
//   LEPARM=''
...

Set up the environment file, properties file, security, tracing and logging

The following sample configuration files can be found in /usr/lpp/ing/restsrvr/config. You need to customize these file before you can start the Operations REST Server.

Sample Configuration File	Description
ing.operations.environment	This environment file is needed to set up the USS environment for the Operations REST Server. System symbols are supported in this file.
ing.operations.properties	This file is used to control various parameters of the Operations REST Server and the integration with other products, such as Zowe™. System symbols are supported in this file.
ing.operations.security.properties	This file is used to set up network security. If you want to set the rate limiter to control the maximum number of calls to the Operations REST API, see Rate Limiter. System symbols are supported in this file.
ing.operations.logging.xml	This file controls how the Operations REST Server writes logs and traces.

Copy the sample configuration files from the directory
/usr/lpp/ing/restsrvrv/config
to your custom directory created in step 27A, for example,
/etc/ing/restsrvr/config
Customize the configuration files to your needs as instructed by the descriptions within the sample files. Here are some considerations that you need to be aware during your customization:
- To use system symbols in these configuration files, see System Symbol Support .
- To enable RACF® or ICSF key kings, see Configure the properties for using RACF or ICSF key rings.
- To set the maximum Operations REST API calls for security reasons, see Rate Limiter.

System Symbol Support

This feature resolves system symbols in the configuration variables at startup. This enables the user to have a generic configuration file that acts as a "single source of truth" and can be shared across systems and sysplexes. The specific configuration for each system can then be controlled via system symbols.

By default, this feature is disabled. To enable this feature, navigate to the file 'ing.operations.environment' and set the following property to true.

# Enable system symbol support [true/false].
ENABLE_SYSTEM_SYMBOL_SUPPORT=true

After the feature is enabled, you can use system symbols in the 'ing.operations.environment', 'ing.operations.properties', and ing.operations.security.properties files.

Example 1, ing.infobroker.environment:

REST_API_CONFIG_HOME=/etc/&SYSNAME./ing/restsrvr

On SYS1, this setting resolves to REST_API_CONFIG_HOME=/etc/SYS1/ing/restsrvr.

On SYS2, this setting resolves to REST_API_CONFIG_HOME=/etc/SYS2/ing/restsrvr.

Example 2, ing.operations.properties:

ing.service.port=&SAROPORT.

On PLEX1, this setting resolves to ing.service.port=8443.

On PLEX2, this setting resolves to ing.service.port=9443.

Configure the properties for using RACF or ICSF key rings

System Automation Operations REST Server can use RACF or ICSF (Integrated Cryptographic Service Facility) key rings to manage certificates if configured accordingly for the OPT_EMBEDDED_WEBSERVER option.

A single RACF or ICSF key ring can be used as keystore and truststore in parallel, holding the required certificate for the embedded web server to provide TLS/HTTPS and the necessary CA certificates for validation, for example, if Zowe is used for JWT token authorization.

If desired, two RACF or ICSF key rings can be used for that purpose as well. It is also possible to use two different keystore and truststore types in parallel. For example, store the own certificate for TLS/HTTPS in a RACF or ICSF key ring and manage the trusted certificates in a PKCS12 file in USS.

To use a RACF or ICSF key ring, complete the following configurations:

Navigate to the ing.operations.environment configuration file. Ensure that the ENABLE_KEYRING_SUPPORT property is set to true and use appropriate IBM_CRYPTO_PROVIDER value. Starting from OA62518, RACF key ring is enabled by default.
- For RACF key ring, use IBM_CRYPTO_PROVIDER="com.ibm.crypto.zsecurity.provider"
- For ICSF key ring, use IBM_CRYPTO_PROVIDER="com.ibm.crypto.hdwrCCA.provider"

Navigate to the ing.operations.security.properties configuration file, set the keystore, truststore, or both properties to the following values:

Table 1. Properties for using RACF or ICSF key rings
Properties	Value	Description
ing.security.tls.keystore / ing.security.tls.truststore	safkeyring://<`USERID`>/ <`KEYRING_NAME` safkeyring://<`USERID`>/<`KEYRING_NAME`>	The URL that specifies the TSO user ID (owner of the key ring) and the name of the RACF or ICSF key ring to use as keystore or truststore.
ing.security.tls.keystore.type / ing.security.tls.truststore.type	To use a RACF key ring, set the value to `JCERACFKS`. To use an ICSF key ring, set the value to `JCECCARACFKS`.	The RACF or ICSF keystore type.
ing.security.tls.keystore.password / ing.security.tls.truststore.password	password	RACF or ICSF key rings are not password protected. Instead, the necessary RACF or ICSF permissions are checked for the user ID specified in these properties: ing.security.tls.keystore ing.security.tls.truststore Since an empty value is not allowed for this property, the value must be 'password'.
ing.security.tls.key.alias	<`LABEL`>, for example, tomcat	The label (alias) that is used to connect the own certificate with the RACF or ICSF key ring. Not required if a RACF or ICSF key ring is used as truststore.

For details of how to manage certificates with RACF, see Using RACF with Encryption Facility in z/OS® documentation. For more information about ICSF, see Get Started with ICSF in z/OS documentation.

Rate Limiter

A rate limit is the maximum number of calls you want to allow in a particular time interval. Setting rate limits enables you to manage the network traffic for this Operations REST API. With the rate limiter, you can specify the number of calls to be accepted within a defined time period. For example:

5 calls per 10 second
100 calls per minute
200 calls per hour

Rate limits are hard. It means if a call exceeds the limit, then the call is aborted and an error is returned. When the rate limit is reached, no more calls are accepted from that user until the beginning of the next time period. For example, you might want to permit a total of 1000 calls per hour (rate limit). If a user makes 1000 calls in the first 10 minutes, they cannot complete any more calls until the hour has expired.

Rate limit is enabled by default for each unique IP address or each authenticated user ID. The rate limit for IP addresses will be applied for every API call before the user authentication happens. The rate limit for user IDs will be applied after a successful authentication. By default, rate limiter allows a maximum of 100 requests within 1 minute for each unique IP address and a maximum of 60 requests within 1 minute for each authenticated user ID.

Note: Since this feature is security-related, it is an opt-out approach. Keep in mind that rate limiter is a breaking change as it can cause issues for client applications that do not handle the appropriate HTTP error code.

To configure rate limit settings, modify the rate-limit-related properties as described in the following table or in the ing.operations.security.properties file.

Properties	Description
ing.security.rate-limit.enabled	Enable or disable the security feature to limit the number of API requests from a single IP address or a user ID.
ing.security.rate-limit.<type>.enabled	Enable or disable the security feature to limit the number of API requests for the specific type. Valid types are: ip-address: rate limit for unique IP addresses. userid: rate limit for each authenticated user ID. Note: The rate limit for IP addresses will be applied for every API call before the user authentication happens. The rate limit for user IDs will be applied after a successful authentication.
ing.security.rate-limit.<type>.requests	Maximum number of requests that should be allowed within the configured time period from a unique IP address or a unique user ID.
ing.security.rate-limit.<type>.time	Amount of time after which the rate limit should be completely reset. By default, this configuration allows a maximum of 100 requests within 1 minute for each unique IP address.
ing.security.rate-limit.ip-address.unit	Time unit allowed for the rate limit. Valid units are: seconds minutes hours days