Integrate with DX RESTmon

Define various sections in the restmon.json file to configure the connection to the DX Operational Intelligence (OI) and to your third-party application data source.
For more information about how to integrate DX RESTmon, see Ingest Third-Party Data with DX RESTmon and Using DX RESTmon.
Using DX RESTmon
Define various sections in the
restmon.json
file to configure the connection to the DX Operational Intelligence (OI) and to your third-party application data source.
Download the RESTmon Package
The RESTmon package is a component of the DX Gateway package. DX Gateway contains RESTmon, On-Premise Gateway, On-Premise ITSM, and Log Collector. For more information, see DX Gateway.
Follow these steps:
  1. Log in with Administrator privileges to DX Platform.
  2. Click
    Settings
    .
  3. Click
    Downloads
    ,
    DX Gateway
    to download the RESTmon package.
Unzip the package and navigate to the <
DX-GATEWAY
>\Restmon folder to find the RESTmon resources.
Contents of the RESTmon Package
The RESTmon package contains the following folders:
  • config
    - This folder contains the application.properties file that is required to configure the port and communication parameters. It also contains the
    restmon.json
    files for the respective schemas. This folder contains the
    application.properties
    file that is required to configure the port and communication parameters. It also contains the
    restmon_v0.json
    and
    restmon.json
    files for the respective schemas. The
    restmon_v0.json
    file is for backward compatibility.Additionally, this folder includes a default KeyStore file
    restmon.keystore
    , which is used for HTTPS communication.
  • profile
    - This folder contains reference profile information that is used to add to the restmon.json file for the respective schema.
  • restmon.war
    - This is the RESTmon deployable file.
  • sample_restmon_json
    - This folder contains reference information that is used to create the restmon.json file during the initial deployment.
  • schema
    - This folder contains out-of-the-box RESTmon schemas.
RESTmon Deployment
Use the following steps to configure and deploy RESTmon. RESTmon is part of the DX Gateway package and uses the common installer for RESTmon, On-Premise Gateway, On-Premise ITSM, and the Log Collector. For more information, see DX Gateway.
This procedure assumes the following:
  • You have configured the
    generic_config.json
    file from the <
    DX-GATEWAY_Installation_Directory
    >\Config folder.
  • You have used the DX Gateway common installer to deploy RESTmon.
For more information, see DX Gateway.
For more information, see DX Gateway.
  1. Verify that RESTmon has been deployed successfully by verifying that the Swagger UI for the REST APIs is accessible. Typically this is at "
    http://
    <localhost>
    :8080/restmon/api/swagger-ui.html
    ". Or review the log file at <
    DX-GATEWAY_Installation_Directory
    >\Logs\restmon.log.
  2. Add profile to the restmon.json file by using the Add Profile API.
    • Navigate to
      RESTmon > profile > <name>_profile.json
      file to copy and modify the profile information.
    • The following snapshot illustrates the Add Profile section in the Swagger UI: Add Profile on DX RESTmon
  3. Upload the schema by using the Upload Schema API.
    The schema name is case-sensitive. Verify that the schema name matches the schema file name.
    The following snapshot illustrates the Upload Schema section in the Swagger UI:
    Add Profile on DX RESTmon
  4. Perform all other operations using the RESTmon APIs accessible at  "http://
    <localhost>
    :8080/restmon/api/swagger-ui.html".
    You can perform additional configuration on the
    restmon.json
    and the schema files which will enable you to push your third-party application data to DX Operational Intelligence based on your environment.
Starting and Stopping DX RESTmon
  • run.bat
    and run.sh- Starts the RESTmon Connector on Windows and Linux respectively.
  • stop.bat
    and stop.sh - Stops the RESTmon Connector on Windows and Linux respectively. Performing this procedure immediately stops all the processing jobs.
Support for Basic Authentication
DX RESTmon supports basic authentication by default. When you access the Swagger interface and the APIs, you are prompted for authentication. This helps ensure that unauthorized users are not allowed to perform any operations. The default credentials are
admin
/
password
. You can also modify these credentials (if required).
Modify Default Credentials
You can modify the default credentials, if required. To do so, you need to perform appropriate configurations in the application.properties file.
Follow these steps:
  1. Navigate to the
    ../config/application.properties
    file.
  2. Locate the following parameters:
    • security.user.name
      - Enter the user name based on your requirements. The default value is
      admin
      .
    • secuirty.user.password
      - Enter the required password. The default value is
      password
      (encrypted format)
    • passwordEncrypted
      - Change the value to
      false
      . When the application is started after this configuration, the encryption is enabled (changed to
      true
      ) and is applied at the start of the application. The password that you provide in plain text is then encrypted. The default value of this parameter is
      true
      .
  3. Save your changes.
  4. Run the DX RESTmon executable file.
You have successfully modified the default credentials. You can now use the updated credentials when prompted.
HTTPS Support
By default, DX RESTmon uses HTTPS for all inbound and outbound communication. This implies that all the incoming/outgoing data is sent over HTTPS, making the data transfer more secure. Verify that the following parameters in the application.properties file have the correct values for the HTTPS support:
  • server.port
    - Specifies the server port for HTTPS. The default value is 8443.
  • server.ssl.key-store-type
    - Specifies the KeyStore format (JKS or PKCS12). The default value is PKCS12.
  • server.ssl.key-store
    - Specifies the path to the KeyStore which contains the certificates.
  • server.ssl.key-store-password
    - Specifies the password used to generate the certificate.
  • server.ssl.key-alias
    - Specifies the alias mapped to the certificate.
  • isKeyStorePasswordEncrypted
    - Specifies whether the KeyStore password is encrypted or not.
The default KeyStore file (
../config/restmon.keystore
) is packaged with DX RESTmon. However, if you want, you can generate a self-signed certificate or use your SSL certificate and update the details accordingly in the application.properties file. The Swagger URL to be used is https://<restmon-hostname>:8443/restmon/api/swagger-ui.html.
Additionally, you can also encrypt the KeyStore password. To do so, enter the password for your KeyStore in the server.ssl.key-store-password parameter and set the value of isKeyStorePasswordEncrypted to false. When the application is started after this configuration, the encryption is enabled (changed to
true
) and is applied at the start of the application. The password that you provide in plain text is then encrypted.
The following snippet shows the section of the file required for HTTPS:
# httpsserver.port=8443server.ssl.key-store-type=PKCS12server.ssl.key-store=config/restmon.keystoreserver.ssl.key-store-password=restmonserver.ssl.key-alias=restmonhttpsaug2019isKeyStorePasswordEncrypted=false
Change from HTTP to HTTPS
If you are already using HTTP for DX RESTmon and want to use HTTPS as the data transfer type, you can enable HTTPS by generating an SSL certificate and modifying the application.properties file.
Follow these steps:
  1. Create a self-signed
    SSL certificate
    . We recommend the
    PKCS12
    format.
  2. Open your command prompt and enter the following command.
    keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore keystore.p12 -validity 3650
  3. As an output of this command, you will be asked to enter the password for your
    Keystore
    .
  4. Once your password is accepted, you will be asked some information to enter like first name, last name, city, country but you can skip those.
  5. Once you have entered all the required information, a
    Keystore
    is created.  Verify the Keystore using the following command:
    keytool -list -v -storetype pkcs12 -keystore keystore.p12
  6. Now we have SSL Certificate ready, the only thing that is remaining is changing your application.properties file.
  7. Open the application.properties file located in the
    RESTMON_DIR
    /config directory.
  8. Comment the HTTP section by adding
    #
    .
  9. Uncomment the following HTTPS options by removing # and updating your configuration:
    • server.port
      - Specifies the server port for https.
    • server.ssl.key-store-type
      - Specifies the keystone format (JKS or PKCS12).
    • server.ssl.key-store
      - Specifies the path to the keystone which contains the certificates.
    • server.ssl.key-store-password
      - Specifies the password used to generate the certificate.
    • server.ssl.key-alias
      - Specifies the alias mapped to the certificate.
    • security.require-ssl
      - Specifies if only HTTPS requests should be accepted. The following is a sample of the configuration options for HTTPS:
      # https server.port=8443 server.ssl.key-store-type=PKCS12 server.ssl.key-store=config/restmon.keystore server.ssl.key-store-password=restmon server.ssl.key-alias=restmonhttpsaug2019 isKeyStorePasswordEncrypted=false security.require-ssl=true
  10. Save the
    application.properties
    file.
  11. Run the
    RESTmon
    executable file.
  12. Verify your changes by accessing the REST APIs using HTTPS at
    "https://localhost:8443/restmon/api/swagger-ui.html"
    .
Configure Proxy
If the Data Source or the DX Operational Intelligence environment is configured with proxy, use the following samples to update the respective JSON files. RESTmon supports following authentication types for a proxy configuration:
  • Basic
  • Digest
  • OAuth
  • NTLM
Data Source Proxy
If your data source is configured with proxy, then add the following proxy information in the profile sectionThe following is a sample snippet, replace the values with your environment details.
"proxy" : { "type" : "<http|https>", "hostname" : "<proxy host name or ip address>", "port" : "<proxy port >", "authentication" : "<authentication type>", "username" : "<proxy username>", "password" : "<proxy password>", "realmdomain" : "<realm>", "token" : "<token>", "httptimeout" : "<time out>", "checkcert" : "<yes|no>" },
Operational Intelligence Proxy
If your DX Operational Intelligence is configured with proxy, then add the following information in RESTmon section of the
restmon.json
file. The following is a sample snippet, replace the values with your environment details.
"oiproxydetails" : { "type" : "<http|https>", "hostname" : "<proxy host name or ip address>", "port" : "<proxy port >", "authentication" : "<authentication type>", "username" : "<proxy username>", "password" : "<proxy password>", "realmdomain" : "<realm>", "token" : "<token>", "httptimeout" : "<time out>", "checkcert" : "<yes|no>" },
Data Source Reverse Proxy
If your data source is configured with reverse proxy, then update the proxy details in the profile section in the
restmon.json
file. The following is a sample snippet, replace the values with your environment details.
"restapiconnectdetails" : { "type" : "<http|https>", "hostname" : "<proxy host name or ip address>", "port" : "<proxy port >", "authentication" : "<authentication type>", "username" : "<proxy username>", "password" : "<proxy password>", "realmdomain" : "<realm>", "token" : "<token>", "httptimeout" : "<time out>", "checkcert" : "<yes|no>" },
Operational Intelligence Reverse Proxy
If your DX Operational Intelligence is configured with reverse proxy, then update the proxy details in the profile section in the
restmon.json
file. The following is a sample snippet, replace the values with your environment details.
"oiconnectdetails" : { "type" : "http", "hostname" : "logcollector.oilab", "port" : "80", "category" : "metrics", "maxnoofdocuments" : "1000", "path" : "/mdo/v2/aoanalytics/ingestion/", "oi_pool_size" : 4 },