Setting up the Common REST API

Common REST API (CRA) version 2.0 is installed through the Installation System with or without BMC AMI Ops Infrastructure version 7.0. Make sure that you have installed the latest ISU refresh.

If you installed BMC AMI Ops Infrastructure version 7.0, you can start using the CRA right away. For more information, see Common-REST-API-data-endpoints.

If you did not install BMC AMI Ops Infrastructure version 7.0, complete the following procedures to configure the CRA server to work with the API. CRA version 2.0 can work with BMC AMI Ops Infrastructure versions 7.0 or 6.3.

The following procedures are available:

To customize the CRA server to work with the API

  1. To complete the copy of your CRA server to the USS directory that you specified on the configuration panel, from UBMCSAMP, run the CRAZFS job from the JCL data set.
  2. After the job runs successfully, copy PROC CRATCJCL from the JCL data set to your started task proclib.

The CRA server starts with the proclib. You can also start and stop the server manually. For information, see To start and stop the CRA serverlater in this topic.

To verify the maintenance level

Messages are issued to the CRA server job log that indicate the maintenance level of the CRA executables.

Example
CRAWAR PTF Level: None

In this example, the PTF level of CRAWAR is None.

If you don’t see the messages in the CRA server job log, then you are running version 1.00 of CRA .

To configure SSL certificates to a keystore as a local file

The CRA component uses TLS authentication to communicate between the API client and the CRA server. Digital certificates are required.

  1. Add a keystore file with the default name, amiops.keystore, to the default directory, installationDirectory/amiops/tomcat/conf, on the CRA server.
    If you want to rename or relocate the keystore file, update the SERVXMLC member of the &INSTALLHLQ.BMCSAMP data set.

    Tip

    For advanced certificate configuration instructions, see the documentation for Apache Tomcat version 9 SSL/TLS configuration.

  2. Restart the server as described later in this topic.

To configure SSL certificates using a SAF keystore

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

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

  2. Configure the TLS connector in the SERVXMLC member of the &INSTALLHLQ.BMCSAMP data set by adding the following attributes:

    • keyAlias—label name of the server certificate
    • keystorePass—must be set as password
    • keystoreType—must be set as JCERACFKS, or if you are using RACF services with ICSF, set this to JCECCARACFKS. 
    • keystoreFile—file in the following format: safkeyring://craUserID/keyringName 
      The value of craUserID is the user ID that runs CRA .
      The value of keyringName is the name you gave to the keyring.
    Example

    The following code shows a connector for SAF:

    <Connector port="&sslPort;" scheme="https" secure="true"        
              maxThreads="150" SSLEnabled="true" clientAuth="false"
              useSendfile="false" enableLookups="false"            
              sslProtocol="TLS"
              relaxedQueryChars='|"'
              keystorePass="password"                     
              keyAlias="server_certificate_label"
              keystoreType="JCERACFKS"            
              keystoreFile="safkeyring://STCUSER/Keyring.CRAK" >
    </Connector>   

    Tip

    For advanced certificate configuration instructions, see the documentation for Apache Tomcat version 9 SSL/TLS configuration.


  3. 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 username and password to connect to the BMC AMI Ops host server. Alternatively, you can use SSL certificates for authentication.

To enable SSL certificates, edit the SERVXMLC member of the &INSTALLHLQ.BMCSAMP data set, and do one of the following:

Note

Make sure to have your keystore.jks and cacerts.jks in the proper locations for the connectors to work.


  • If you want your Tomcat to use the truststore on the RACF, add the following Connector section to the SERVXMLC member and modify the required fields accordingly.

    Example

    The following code sample shows a connector: 

    <Connector port="8441" protocol="HTTP/1.1" SSLEnabled="true"
    maxThreads="150" scheme="https" secure="true"

    truststoreType="JCERACFKS"
    truststoreFile="safkeyring://USERID/Racf_Name"
    truststorePass=""

    keystoreFile="<installationDirectory>/amiops/tomcat/security/keystore.jks" keystorePass="changeit"
    clientAuth="true" sslProtocol="TLS" />

  • If you want your Tomcat to use its own truststore, add the following Connector section to the SERVXMLC member and modify the required fields accordingly.
    The following code sample shows the connector:

    Example

    The following code sample shows a connector: 

    <Connector port="8441" protocol="HTTP/1.1" SSLEnabled="true"
    maxThreads="150" scheme="https" secure="true"

    truststoreFile="< installationDirectory >/amiops/tomcat/security/ cacerts.jks" truststorePass="changeit"

    keystoreFile="< installationDirectory >/amiops/tomcat/security/keystore.jks" keystorePass="changeit"
    clientAuth="true" sslProtocol="TLS" />

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

After you import certificates into a keystore, you can change the port number and host name for the CRA server.

  1. Edit the SERVVARC member of the &INSTALLHLQ.UBBSAMP data set.

  2. To change the HTTPS port number, replace the sslPort value as displayed in italics in the following example:

    <!ENTITY sslPort "18443"> <!-- if SERVXML configured for SSL/TLS -->

  3. (For HTTP) To change the HTTP port number, replace the httpPort value as displayed in italics in the following example:

    <!ENTITY httpPort "15565"> <!-- the Tomcat HTTP port -->

    See To enable CRA use with HTTP later in this topic.

  4. To change the host name to a name other than the LPAR where CRA is configured, replace the hostname value as displayed in the italics in the following example:

    <!ENTITY hostname "localhost"> <!-- normally don't need to change -->

  5. 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. If you want to run CRA with HTTP, perform the following steps:

Warning

Running CRA with HTTP poses a security vulnerability.

We recommend running the component with HTTPS only.

  1. Open the SERVXMLC member of the &INSTALLHLQ.BMCSAMP data set and perform the following tasks:

    1. Uncomment the HTTP connector by removing the <!-- and --> comment markers from before and after the connector and save the file.

      Example

      The following code sample shows the connector:

      <Connector port="&httpPort;" protocol="HTTP/1.1"
      connectionTimeout="20000"
      redirectPort="&sslPort;" />

    2. (Optional) Comment the SSL connector by adding the <!-- and --> comment markers before and after the connector and save the file.

      Example

      The following code sample shows the connector:

      <!--
      <Connector port="&sslPort;" protocol="org.apache.coyote.http11.Http11NioProtocol"
                 maxThreads="150" SSLEnabled="true"                      
                 relaxedQueryChars='|"' >                                
           <SSLHostConfig>                                                
               <Certificate certificateKeystoreFile="conf/amiops.keystore" type="RSA" />                               
           </SSLHostConfig>                                            
       </Connector>    
      -->
  2. Restart the server as described later in this topic.

To start and stop the CRA server

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

The default procedure name is CRATCJCL. 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 /S CRATCJCL command.
    If the server does not start, confirm the settings in the STDERR task of the CRATCJCL job.
  • To stop the CRA server, in the spool (SDSF), use the /P CRATCJCL command.

Modifying CRA properties

The application.properties file, located on the CRA server in the installationDirectory/amiops/config directory, contains properties that you can modify to better fit your organization's needs.

Best practice
BMC recommends contacting BMC Support before modifying the properties.

If you installed the BMC AMI Ops user interface, the properties in this file affect the behavior of that component, too. Some properties apply only to BMC AMI Ops UI. The properties listed in the following table affect the behavior of BMC AMI Ops UI and CRA .

Property

Default value

Description

request.timeout

60

Number of seconds before a request from the server to the service times out

The value must be less than the client.request.timeout value.

token.timeout

15

Number of minutes before the access token times out and the user must log in again

The value must be 5 minutes or higher.

For more information about tokens, see Managing-Common-REST-API-session-tokens-and-user-tokens.

ami.ops.ui.log.level

INFO

Logging level for the server

Valid values are ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, and OFF

After you change a property value, you must restart the CRA server.

To Enable the Swagger interface with AT-TLS

If your CRA port is set to use AT-TLS, make the following change to enable the Swagger interface:

  1. Open the application.properties file, located on the CRA server in the installationDirectory/amiops/config 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>
    Example

    swagger.url=https://myserver.com:8080

    Important

    Make sure the URL is to https, not http.

To enable TLS communication with BMC AMI Ops Automation

  1. Open the application.properties file, located on the CRA server in the installationDirectory/amiops/config directory.

  2. Add the following lines:

    opsa.keystore.file=<filepath>
    opsa.keystore.password=<password>

    opsa.keystore can be a full path or a relative path of installationDirectory/amiops/tomcat.

  3. The default keystore type is PKCS12. If you are using a JKS keystore, add the following line:
    opsa.keystore.type=JKS

Where to go from here

When you finish setting up the CRA server, you can do one or more of the following tasks:

If you are not seeing the data you expect, see Troubleshooting-Common-REST-API.

Related topics

Managing-Common-REST-API-session-tokens-and-user-tokens

Administering-the-Common-REST-API

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*