Setting up the Common REST API

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

If you installed MainView 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 MainView 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 MainView Infrastructure versions 7.0 or 6.3.

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 in the server XML file:

    • keyAlias—label name of the server certificate    
    • keystorePass—must be set as password
    • keystoreType—must be set as JCERACFKS
    • 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 MainView 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.

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

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

BMC recommends running the component with HTTPS only.

  1. Open the SERVXMLC member of the &INSTALLHLQ.BMCSAMP data set.

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

    The following code sample shows the connector:

    <Connector port="&httpPort;" protocol="HTTP/1.1"
    connectionTimeout="20000"
    redirectPort="&sslPort;" />
  3. 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 Operations user interface, the properties in this file affect the behavior of that component, too. Some properties apply only to

Some content is unavailable due to permissions.

. The properties listed in the following table affect the behavior of

Some content is unavailable due to permissions.

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.

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*