Setting up CRA to work as a stand-alone server

This topic explains how to set up CRA as a stand-alone server.

Setting up a working directory with write access for CRA

You can configure the CRA server or CMF Integration server to setup a working directory to manage the log and configuration files. Since the installation directory (where you have installed the CRA server) has read only access, you can set up a working directory that has write access.

To setup a working directory:
- For CRA server, set the following environment variables in the CRATCENV member of the &INSTALLHLQ .BMCSAMP data set:

- - CLASSPATH="${CRA_INSTALL_PATH}"/cra.jar
  - CRA_HOME=full path of the working directory with read and write access

- For CMF Integration server, set the following environment variables in the GPMTCENV member of the &INSTALLHLQ .BMCSAMP data set:

- - CLASSPATH="${GPM_INSTALL_PATH}"/gpm.jar
  - GPM_HOME=full path of the working directory with read and write access
Copy the following files from the installation directory to the working directory that you have created.
Important
The installation directory contains the following files:
- If you have installed CRA as a stand-alone server:
  - configurations.json
  - cra_custom.properties
  - cralog4j2.xml
- If you have installed CMF Integration server:
  - gpm_configurations.json
  - gpm_custom.properties
  - gpmlog4j2.xml
  - m3mapping.json
  - mapping.json
Make sure that you copy the required files to the working directory whenever you upgrade the CRA server.
Restart the server as described later in this topic.

To enable an SSL connection to the CRA server

The CRA component can use the TLS authentication to communicate between the API client and the CRA server. For the keystore, you can either use a local file or SAF keyring.

To use a local keystore

Add a keystore file with the extension .keystore to the USS installation directory on the CRA server.
To rename or relocate the keystore file, update the CRACMNEV member of the &INSTALLHLQ .UBMCSAMP data set.

In the CRACMNEV member, set the following keystore details. These values are the same as those you entered during installation on the Common Rest API Options panel.

Important

You must not add or delete keys to the CRACMNEV member. Adding or deleting keys in CRACMNEV member can cause unexpected behavior from the product.

Keystore property	Description
AMICRA_SSL	Confirm to use an SSL protocol Must be set as true to use an HTTPS connection. To use a non-SSL (HTTP) connection, set the value as false. Important We recommend using an SSL (HTTPS) connection because running CRA with HTTP might cause a security vulnerability.
AMICRA_PROTOCOL	Type of connection Must be set as https
AMICRA_KEYSTORE_TYPE	Type of keystore Set the SSL certificate (keystore) type (JKS or PKCS12). For more information about supported keystores, see the IBM SDK, Java Technology Edition documentation.
AMICRA_KEYSTORE_ALIAS	An alias value for a single data key
AMICRA_KEYSTORE_PASSWORD	Keystore password
AMICRA_KEYSTORE_NAME	USS location of the keystore

Restart the server as described later in this topic.

To use a SAF keystore

You can configure HTTPS connection with keyring support for system authorization facility (SAF) user ID.

Configure your keystore with SAF.
Example
For RACF, perform the following steps:
1. Create a keyring.
2. Obtain a CA certificate.
3. Create a server certificate.
4. Connect the keyring with a server certificate.
5. Connect the keyring with a CA certificate.
The following image displays how the keyring looks after it is configured for RACF:
                RACF - List Ring Names
COMMAND ===> _
                                                                More:

Ring:
Keyring.CRAK

Certificate Label Name              Cert Owner USAGE       DEFAULT
---------------------------------   ----------- --------    --------
  craServer                       ID(STCUSER) PERSONAL   NO
  cra                               CERTAUTH     CERTAUTH   NO

In the CRACMNEV member, set the following keystore values:

Keystore property	Description
AMICRA_SSL	Confirm to use an SSL protocol Must be set as true to use an HTTPS connection. To use a non-SSL (HTTP) connection, set the value as false. Important We recommend using an SSL (HTTPS) connection because running CRA with HTTP might cause a security vulnerability.
AMICRA_PROTOCOL	Type of connection Must be set as https
AMICRA_KEYSTORE_TYPE	Type of keystore (For example, JCERACFKS)
AMICRA_KEYSTORE_ALIAS	An alias value for a single data key (Certificate Label Name)
AMICRA_KEYSTORE_PASSWORD	Must be set as password
AMICRA_KEYSTORE_NAME	Keyring details in the following format: safkeyring://craUserID/keyringName The craUserID value is the user ID that runs. The keyringName value is the name you gave to the keyring.

Restart the server as described later in this topic.

To configure CRA server ciphers

Open the cra_custom.properties file that is located on the CRA server in the installationDirectory/cra directory.
Add the following key:
server.ssl.ciphers=<value>
server.ssl.ciphers=TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384(% class="auto-cursor-target" style="color: rgb(23,43,77);" %)
Restart the server as described later in this topic.

Some content is unavailable due to permissions.

To configure the JSON Web Tokens secret key

CRA uses JSON Web Tokens (JWT) to manage the login token. After installation, the JWT key becomes static across the systems. Therefore, we recommend performing the following steps to update the key to make it unique and secure for your system:

Open the cra_custom.properties file that is located on the CRA server in the installationDirectory/cra directory.
Add the jwt.secret key.
jwt.secret=ThisIsTheKeyThatCanBeChangedButMustBeSameLengthWhichI64ByteLengthWe recommend changing the default, which is common to all installations.
Restart the server as described later in this topic.

To enable SSL certificates for connecting to BMC AMI Ops

By default, CRA requires you to use a user name and password to connect to the host server. Alternatively, you can use SSL certificates for authentication.

Enable the SSL connection to CRA server as described in this topic.
In the CRACMNEV member, perform the following tasks:
- Uncomment the following IJO properties from the CRATCENV member, which is located in the BMCSAMP data set.
  Important
  #IJO="$IJO -Dserver.ssl.trust-store-type=${AMICRA_TRUSTSTORE_TYPE}"
  #IJO="$IJO -Dserver.ssl.trust-store-password=${AMICRA_TRUSTSTORE_PASSWORD}"
  #IJO="$IJO -Dserver.ssl.trust-store=${AMICRA_TRUSTSTORE_NAME}"
- If using a SAF Keyring, set the following parameter values:
  - AMICRA_TRUSTSTORE_TYPE—must be set as JCERACFKS or JCECCARACFKS
  - AMICRA_TRUSTSTORE_NAME— the truststore path (for example, safkeyring://USERID/Racf_Name)
  - AMICRA_TRUSTSTORE_PASSWORD—must be set as password
  - AMICRA_CLIENT_AUTH—must be set as NEED
- If using local truststore file system, set the following parameter values.
  - AMICRA_TRUSTSTORE_TYPE—must be set as JKS or PKCS12
  - AMICRA_TRUSTSTORE_NAME—the truststore path (for example, <installationDirectory >/cra/mycert.jks )
  - AMICRA_TRUSTSTORE_PASSWORD—the truststore password
  - AMICRA_CLIENT_AUTH—must be set as NEED
    Important
    A client certificate is supported with MVE host server version 7.00 or later only. If you want to use the client certificate, configure the CRA server with AMICRA_CLIENT_AUTH=NEED.
    If you are using the Swagger login request, do not include any parameters in the request body as shown in the following figure:
    {
    }
    
    Make sure that the client certificate is trusted by RACF on the host server LPAR.
Restart the server as described later in this topic.

To change the port number and host name on the CRA server

You can change the port number and host name for the server. Perform the following steps:

Edit the CRACMNEV member of the &INSTALLHLQ . UBMCSAMP data set and specify the following parameter values:
- AMICRA_PORT—BMC CRA server port number (default value: 15563)
- AMICRA_HOST—BMC CRA server host name (default value: localhost)
Restart the server as described later in this topic.

To enable CRA use with HTTP

By default, the CRA server is set to run with HTTPS. To run CRA with HTTP, perform the following steps:

Edit the CRACMNEV member of the &INSTALLHLQ .UBMCSAMP data set and set the following parameter values:
- AMICRA_SSL—must be set as false
- AMICRA_PROTOCOL—must be set as http
Restart the server as described later in this topic.
Warning
If you are not running CRA port with AT-TLS, running CRA with HTTP poses a security vulnerability. We recommend running the component with HTTPS only.

To configure the CRA port to use AT-TLS

To configure the CRA port to use AT-TLS, you must first configure the server as Non-TLS.

Make the following changes:

Follow To enable CRA use with HTTPto configure CRA to use HTTP.
To enable the Swagger interface:
1. Open the cra_custom.properties file that is located on the CRA server in the installationDirectory/cra directory.
2. Add the following key:
  swagger.url=property to the secured URL of your CRA server as follows:
  swagger.url=https://<cra_host>:<cra_port>/cra
  swagger.url= https://myserver.com:15563/cra
  Important
  Make sure that the URL is to https, not http.
Restart the server as described later in this topic.

To use Zowe to access the BMC Common REST API

You can access CRA through the Zowe interface. For more information, see Using-Zowe-to-access-the-BMC-Common-REST-API.

To start and stop the CRA server

The CRA server is a web server that is installed on the USS mainframe as part of the standard installation.

The default procedure name is CRATCSRV. Replace the name with the procedure name you specified when you installed the component.

To start the CRA server, in the spool (SDSF), use the following command:

/S CRATCSRV

If the server does not start, confirm the settings in the STDERR task of the CRATCSRV job.

To stop the CRA server, in the spool (SDSF), use the following command:

/P CRATCSRV

To modify CRA timeouts properties

Edit the CRACMNEV member of the &INSTALLHLQ . UBMCSAMP data set and specify the following parameter values:
- AMICRA_BACKEND_REQUEST_TIMEOUT—(Modify only if required) number of seconds before a request from the server to the service times out. The default value is 60 seconds.
- AMICRA_TOKEN_TIMEOUT—(Modify only if required) number of minutes before the access token times out and the user must log in again. The default value is 15 minutes. Make sure that the specified value is 5 minutes or more.
Restart the server as described later in this topic.

To enable TLS communication with BMC AMI Ops Automation