symrest.json reference

Location

Parameters

The symrest.json file works with the symrest.xml service profile. Use the symrest.json file to define workload submission parameters for a RESTful API client, or to manage IBM Spectrum Symphony workload; use the symrest.xml service profile to define standard environment variables to run the service, much like any other EGO service (see Service profile reference).

symrest

Required. Define the parameters in this section to secure communication between the SYMREST server and the RESTful API over TLS.

portRange

Range of listening ports for the SYMREST service. Valid value is a port number in the format minimum_port, maximum_port. Ensure that the minimum port number does not exceed the maximum port number.

Default: 8050, 8060

listenHostIP

When your Windows management hosts use private and public IP addresses, specifies the public IP address on which the SYMREST service must listen. (On Linux management hosts, the SYMREST service listens on all available IP addresses.) For a Windows management host with only one IP address, this parameter is not required.

A public IP address enables SYMREST to be accessible from outside the cluster. Valid value is the partial string of a public IP address. For example, when the host's private IP address is 9.24.2.1 and the public IP address is 9.23.3.2, define this parameter as "9.23" or "9.23.3".

Note: When primary host failover is enabled in your cluster, do not define the complete IP address (for example, "9.23.3.2"). Only a partial string can allow the public IP address on any other management host to be found after failover.

Default: Not defined

transport

Enables or disables secure TLS communication between the SYMREST service and the RESTful API. Valid values are TCPIPv4SSL (enables TLS authentication) or TCPIPv4 (disables TLS authentication). TLS communication for RESTful APIs follows your security setting for web servers, which is enabled during installation by default. If you disabled security for web server communication during installation, security for RESTful APIs is also disabled. For more information, see Securing communication with RESTful API workload for SYMREST.

Default: TCPIPv4SSL (with secure TLS for RESTful web servers enabled)

transportArg

TLS arguments for the SYMREST service when security is enabled. The transportArg parameter uses the same subparameters as the EGO_DEFAULT_TS_PARAMS parameter, which is defined in the ego.conf file for cluster-level TLS configuration. For SYMREST purposes, the key subparameters are CERTIFICATE and PRIVATE_KEY. Alternatively, you can define an environment variable (for example, $EGO_DEFAULT_TS_PARAMS_WIN_P12 on Windows and $EGO_DEFAULT_TS_PARAMS on Linux), to retrieve TLS configuration from the ego.conf file on the management host that runs the SYMREST service.

For testing on Linux hosts, IBM Spectrum Symphony provides a built-in self-signed certificate (see Enabling security for RESTful API workload using SYMREST (default certificate)); for Windows hosts, you must generate a PKCS certificate in .p12 format. For your production environment, use a properly chained certificate that is issued or signed by a trusted certificate authority (see Enabling security for RESTful API workload using SYMREST (external certificate)).

Default: $EGO_DEFAULT_TS_PARAMS

• Linux: $EGO_DEFAULT_TS_PARAMS
• Windows: $EGO_DEFAULT_TS_PARAMS_WIN_P12

soamConnectionTimeoutInSeconds

Timeout (in seconds) for the SYMREST server when you use the SOAM API SoamFactory::connect to create a connection to the specified application.

Default: 15

soamRequestTimeoutInSeconds

Timeout (in seconds) for the SYMREST server when tasks are sent to the session manager (SSM).

Default: 15

soamSessionIdleTimeoutInMinutes

Duration (in minutes) that the SYMREST server waits to close a session that does not have any active tasks.

Default: 60

workerThreads

Maximum number of concurrent workload requests that can be processed in parallel. Valid value is an integer in the range 1 - 64.

Default: 8

inclusionList

List of applications and the clusters that they can be found in. If not defined, application access is not permitted. For more information, see Managing workload from a RESTful API client.

clusters

Details of clusters that host the applications to which the client can submit workload. If your installation is a single cluster, you don't need to define this parameter. If your installation includes multiple clusters, configure details of each cluster, specifically the cluster ID, KD port, and the primary host and primary host candidates in the cluster. Use the format:

clusterID: {

  KDPort: vemkd_port,

  masterList: [primary_host, primary_candidate_host, ...]

}

Default: Not defined

applications

List of applications to which the client can submit workload. Use the format application_name: [clusterID, clusterID_1, ...]. The clusterID parameter is not required for a single cluster. For multiple clusters, the clusterID parameter is optional and specifies one or more clusters to which application workload can be submitted. If a cluster is not specified, workload is submitted to any cluster.

Default:

• Applications: symping7.3.2, Demo7.3.2
• Cluster: Not defined.

loadBalancer

ETCD

URL of the ETCD server in the format https://host_name:port, where host_name identifies the ETCD server host; the default port is 2379.

Default: Not defined

loadUpdateIntervalSecond

Interval (in seconds) at which the SYMREST service sends its URL and load information to the ETCD server.

Default: 60

caFileForETCD

Path to the CA certificate used by the ETCD server.

Default:

openid

Optional for client workload submission. Define the parameters in this section to use OpenID authentication for the RESTful API client to connect to the SYMREST service in your cluster. For more information, see Configuring OpenID authentication for RESTful API client workload.

openIdClientUrl

URL of the OpenID client in the format https://host_name:port, where host_name identifies the management host on which the OpenIdClient service runs on; the default port is 8653. Find the OpenIdClient URL in the $EGO_TOP/soam/openid/logs/OpenIdClient.log file.

Default: Not defined

caFileForOpenIDClient

Path to the CA certificate used by the OpenID client. IBM Spectrum Symphony provides a self-signed CA certificate (cacert.pem), which you can use for testing purposes. For production environments, ensure that you use a properly chained certificate that is issued or signed by a trusted CA.

Default: $EGO_TOP/wlp/usr/shared/resources/security/cacert.pem

openidEgoUserMappingScript

Path to a user-defined script that converts site-specific OpenID user IDs to EGO user IDs, which can then be used to access the IBM Spectrum Symphony cluster. Use your OpenID IdP's instructions and create a script that maps your OpenID users' email ID to EGO user IDs. The script must take each OpenID user's email ID as input and provide the corresponding EGO user ID as output in the format egoUsername:egoPassword (for example, Admin:Admin).

Default: Not defined

Example symrest.json file

"symrest":
{
    "portRange": [8050, 8060],
    "transport": "TCPIPv4SSL",
    "transportArg": "$EGO_DEFAULT_TS_PARAMS",
    "soamConnectionTimeoutInSeconds": 15,
    "soamRequestTimeoutInSeconds": 15,
    "soamSessionIdleTimeoutInMinutes": 60,
    "workerThreads" : 8
},
   "inclusionList":
{
    "clusters": {
       "sym72win": {
          "KDPort": 12501,
          "masterList": ["testhost1"]
       },
       "Sym72Linux": {
          "KDPort": 24501,
          "masterList": ["testhost2"]
       }
    },
    "applications": {
        "symping7.3.2": ["sym732win", "Sym732Linux"]
        "SharingDataCPP": ["sym732win"]
        "Demo7.3.2": []
     }
},
"loadBalancer":
{
    "ETCD": "https://localhost:2379",
    "loadUpdateIntervalSecond": 60,
    "caFileForETCD": ""
},
"openid":
{
    "openIdClientUrl": "https://myOpenIdClienthost.example.com:8653",
    "caFileForOpenIDClient": "$EGO_TOP/wlp/usr/shared/resources/security/cacert.pem",
    "openidEgoUserMappingScript": "/openid/users.sh"
}

"symrest":
{
    "portRange": [8050, 8060],
    "listenHostIP" : "9.23.",
    "transport": "TCPIPv4SSL",
    "transportArg": "$EGO_DEFAULT_TS_PARAMS_WIN_P12",
    "soamConnectionTimeoutInSeconds": 15,
    "soamRequestTimeoutInSeconds": 15,
    "soamSessionIdleTimeoutInMinutes": 60,
    "workerThreads" : 8
},
   "inclusionList":
{
    "clusters": {
       }
    },
    "applications": {
        "symping7.3.2": []
        "Demo7.3.2": []
     }
},
"loadBalancer":
{
    "ETCD": "https://localhost:2379",
    "loadUpdateIntervalSecond": 60,
    "caFileForETCD": ""
}
}