Configuring Common REST API options

You can use Common REST API (CRA) to retrieve data collected by BMC mainframe monitoring products. The CRA server libraries are installed when you install CRA or any BMC AMI Ops product.

To configure version 2.1 of CRA

Important

The steps documented in this topic apply only when configuring CRA to work as a stand-alone server.

For configuring CRA on the IBM WebSphere Liberty server, follow the steps in Setting up CRA to work with the IBM WebSphere Liberty server.

Enter values in the Common Rest API Options panel. For information about these values, see the table that follows the following figure:

Select the required Common REST API Server option (Liberty or Standalone) to
use. If the Liberty Server option value is NO, specify the values for the
Standalone Server option.
                                                                   More:     +
Common Rest API/Liberty User-ID . . . . . . 2222
Common Rest API/Liberty Group-ID . . . . . 2222

Liberty Server Usage:
  Install CRA Application On Liberty Server NO         (YES/NO)
  Liberty Server Base Path . . . . . . . .
/shrd/wlp/usr/servers/WLPSVREJ/dropins

Standalone Server Usage:
  Note: This configuration not needed when installing on Liberty server.
  Common Rest API Started Task Name . . . . CRATCSRV
  Common Rest API Port Number . . . . . . . 15565
  Common Rest API Host Name . . . . . . . .
    localhost
   Note: Port number and host name on which CRA 2.1.0 would be running, the url to access it is: https://<host>:<port>/cra

Common Rest API/CMF Base Path . . . . . .
   /u/MAINVIEW/cra210
Java Home Path . . . . . . . . . . . . .
   /usr/lpp/java/J17.0_64

Enter SSL details to use HTTPS connection or keep default to use BMC
provided self-signed certificate.
SSL Certificate:
   Use SSL Connection . . . . . . . . . . . YES        (YES/NO)
   SSL Type . . . . . . . . . . . . . . . .            (JKS/PKCS12/JCERACFKS)
   SSL Certificate Path Or Key Ring Path . .

   SSL Private Key/Password (If Required) .

   SSL Alias Name . . . . . . . . . . . . .


Client Certificate:
   Client Certificate Needed . . . . . . . . NONE       (NEED/NONE)
   Client Type . . . . . . . . . . . . . . .            (JKS/PKCS12/JCERACFKS)
   Client Certificate Path Or Key Ring Path

   Client Private Key/Password (If Required)


Timeouts:
   CRA Request Timeout . . . . . . . . . . . 60
   Token Timeout . . . . . . . . . . . . . . 15

CMF Integration With z/OSMF Resource Monitoring:
Configure CMF Integration Server . . . . NO         (YES/NO)
CMF Started Task Name . . . . . . . . . . GPMTCSRV
CMF Integration Server Port Number . . . 15567

Section	Field	Value
Liberty Server Usage	Install CRA Application On Liberty Server	Enter YES to install Common REST API on a preinstalled WebSphere Liberty server. Default value: NO.
Liberty Server Usage	Liberty Server Base Path	Enter the full path of the dropins folder under the WebSphere Liberty server directory. For example, /shrd/wlp/usr/servers/WLPSVREJ/dropins
Standalone Server Usage	Common Rest API Started Task Name	Enter the started task name for the Common REST API. The name must not exceed eight characters. Default value: CRATCSRV
	Common Rest API Port Number	Enter the port number on which the Common REST API runs. Default value: 15565 After completing the configuration process, you can access the UI using one of the following link formats: If an SSL connection is enabled: https://<host>:<port>/cra/swagger If an SSL connection is disabled: http://<host>:<port>/cra/swagger
	Common Rest API Host Name	Enter the host name on which the Common REST API application server runs. Default value: localhost After completing the configuration process, you can access the UI using one of the following link formats: If an SSL connection is enabled: https://<host>:<port>/cra/swagger If an SSL connection is disabled: http://<host>:<port>/cra/swagger
	Common Rest API/CMF Base Path	Enter the root path for a CRA directory. You must specify a unique path for a CRA installation. Default value: /u/MAINVIEW/cra210
	Java Home Path	Enter the path for a 64-bit Java17 home directory that exists on the installed host. Default value: /usr/lpp/java/J17.0_64
	Use SSL Connection	Enter YES to use an HTTPS connection. Enter NO to use a non-SSL (HTTP) connection. Important We recommend using an SSL (HTTPS) connection because running CRA with HTTP might cause a security vulnerability. Default value: YES
	SSL Type	If the Use SSL Connection field value is set to YES, enter the SSL certificate (keystore) type (JKS, JCERACFKS, JCECCARACFKS, or PKCS12).
	SSL Certificate Path Or Key Ring Path	If the Use SSL Connection field value is set to YES, enter a keystore path or SAF Keyring used for SSL encryption. For JCERACFKS and JCECCARACFKS, specify the valid keyring details. For other types, specify the UNIX location of the keystore.
	SSL Private Key/Password (If Required)	If the Use SSL Connection field value is set to YES, you must enter a keystore password to be used to protect the integrity of the keystore. The password must contain at least six characters. For JCERACFKS and JCECCARACFKS, the password is password.
	SSL Alias Name	If the Use SSL Connection field value is set to YES, enter the SSL alias name.
	Client Certificate Needed	Enter NEED if a client certificate is required.¹ Default value: NONE
	Client Type	If the Client Certificate Needed field value is set to NEED, enter an SSL certificate type (JKS, JCERACFKS, JCECCARACFKS, or PKCS12) to set up a secure connection.
	Client Certificate Path Or Key Ring Path	If the Client Certificate Needed field value is set to NEED, enter a truststore as a repository of security certificates that is used for SSL encryption. For JCERACFKS and JCECCARACFKS, specify the valid keyring details. For other types, specify the UNIX location of the truststore.
	Client Private Key/Password (If Required)	If the Client Certificate Needed field value is set to NEED, you must enter a truststore password to protect the integrity of the truststore. The password must contain at least six characters. For JCERACFKS and JCECCARACFKS, the password is password.
	CRA Request Timeout	(Change only if required) Enter the maximum time in seconds for the Common REST API Backend server Ops Infrastructure to respond. Default value: 60 seconds
	Token timeout	(Change only if required) Enter the maximum time in minutes a user session is kept active on the server. Default value: 15 minutes
CMF Integration With z/OSMF Resource Monitoring ²	Configure CMF Integration Server	Enter YES to configure CMF integration server with IBM z/OSMF resource monitoring. Default value: NO
	CMF Started Task Name	Enter the started task name for the CMF integration server. Default value: GPMTCSRV
	CMF Integration Server Port Number	Enter the port number on which the CMF integration server runs. Default value: 15567

¹ If the Client Certificate Needed field value is set to NEED, make sure that you uncomment the following statements (by removing # marks) from the CRATCENV member that is present in the &INSTALLHLQ.BMCSAMP data set.

The JCL code sample follows:

Example

#IJO="$IJO -Dserver.ssl.trust-store=${AMICRA_TRUSTSTORE_NAME}"

#IJO="$IJO -Dserver.ssl.trust-store-password=${AMICRA_TRUSTSTORE_PASSWORD}"

#IJO="$IJO -Dserver.ssl.trust-store-type=${AMICRA_TRUSTSTORE_TYPE}"

² To configure the CMF Integration Server to extract BMC AMI Ops Monitor for CMF data, seeConfiguring CRA to extract CMF data.

Version 2.0 of CRA contains the following configuration information:

Click here to expand...

Warning

The CRA server installed and configured was tested for integrity and performance with the BMC application code. Deploying other applications on the server might have unexpected results.

Use the following information to complete the Common RESTful API for TOMCAT options panel during the configuration process.

Important

The following panel information pertains to the earlier (prior to 4.00.00 release) version of the Installation System.

Common RESTful API for TOMCAT options panel

                 Common RESTful API for TOMCAT options
Command ===> ________________________________________________ Scroll ===> CSR

Enter the UNIX File System values and product options.

Runtime UNIX file system options
   Numeric UNIX User-ID . . . . . . . .
   Numeric UNIX Group-ID . . . . . . . .
   Root directory for Common RESTful API for TOMCAT file path


Common RESTful API for TOMCAT properties
   TOMCAT host name . . . . . . . . . . localhost
   TOMCAT port number (HTTP) . . . . . . 15565
   TOMCAT SSL port number (SSL/TLS) . . 18443
   TOMCAT AJP port number (SSL/TLS) . . 18010

Field	Description
Numeric UNIX User-ID	A numeric UNIX user ID (USS UID) for the file system. If you are unsure of the USS UID, consult your security administrator. Important The USS UID requires update access to the root directory.
Numeric UNIX Group-ID	A numeric UNIX group ID (USS GID) for the file system. If you are unsure of the USS GID, consult your security administrator.
Root directory for Common RESTful API for TOMCAT file path	The location of the Tomcat and Java directories for the CRA. Additional directory levels might be appended to the path provided. Important You must specify an absolute path without any symbolic links in the path or the Installation System will not create the files properly. Specify a unique file path (not a common root file path or a path entered for other installations) to be used exclusively by CRA. This directory is deleted and redefined during the installation (by the CRAZFS job) to overwrite any older files.
TOMCAT host name	The host name by which you will access CRA. By default, this is the LPAR name where you complete the configuration. You can specify a different host name instead.
TOMCAT port number (HTTP)	The default port number for the Tomcat server used by CRA when you are using the HTTP protocol. Specify the port number that you have reserved for CRA. This value determines the URL for launching CRA. The URL will be: http://localHost/LPAR>:specifiedPort/amiops/login
TOMCAT SSL port number (SSL/TLS)	The default port number for the Tomcat server used by CRA when you are using the HTTPS protocol. Specify the port number that you have reserved for CRA. This value determines the URL for launching CRA. The URL will be: https://localHost/LPAR>:specifiedPort/amiops/login
TOMCAT AJP port number (SSL/TLS)	The default port number for the Tomcat server used by CRA when you are using the AJP protocol. Specify the port number that you have reserved for CRA. This value determines the URL for launching CRA. The URL will be: ajp://localHost/LPAR>:specifiedPort/amiops/login

Configuring Common REST API options

To configure version 2.1 of CRA

On this page