Configure the REST LAM

The REST LAM allows Moogsoft Onprem to receive data from REST-compliant web services. REST LAM accepts HTTP and HTTPS requests in all varieties of JSON, XML and YAML formats and parses them into Moogsoft Onprem events.

You can use cURL commands to test whether you have correctly configured the REST LAM to accept REST messages. See the examples provided for more information.

The REST LAM responds to the data sender with standard HTTP response codes and JSON messages.

Before You Begin

Before you configure the REST LAM, ensure you have met the following requirements:

You have network access to the host address and port.
The port is open through the server firewall.
You understand the message data format you will send to the REST LAM.

If you are configuring a distributed deployment refer to High Availability Overview first. You will need the details of the server configuration you are going to use for HA.

Configure the LAM

Edit the configuration file to control the behavior of the REST LAM. You can find the file at $MOOGSOFT_HOME/config/rest_lam.conf

See the LAM and Integration Reference for a full description of all properties. Some properties in the file are commented out by default. Uncomment properties to enable them.

Configure the properties for the REST connection:
- port: Port on the Moogsoft Onprem server that listens for REST messages. Defaults to 8888.
- address: Address on the Moogsoft Onprem server that listens for REST messages. Default to all interfaces.
- expose_request_headers: Allows you to include request HTTP headers in Moogsoft Onprem events.
Configure authentication:
- authentication_type: Type of authentication used by the LAM. Defaults to none.
- basic_auth_static: Username and password used for Basic Auth Static authentication.
- jwt: The claims used for JSON Web Token, if the authentication type is set to JWT.
  For more information on JSON Web Tokens, see Introduction to JSON Web Tokens
- authentication_cache: Whether to cache the username and password for the current connection when the authentication type is Basic.
- auth_token or encrypted_auth_token: Authentication token in the request body.
- header_auth_token or encrypted_header_auth_token: Authentication token in the request header.
Configure the LAM behavior:
- num_threads: Number of worker threads to use when processing events.
- rest_response_mode: When to send a REST response. See the LAM and Integration Reference for the options.
- rpc_response_timeout: Number of seconds to wait for a REST response.
- event_ack_mode: When Moogfarmd acknowledges events from the REST LAM during the event processing pipeline.
- accept_all_json: Allows the LAM to read and process all forms of JSON.
- lists_contain_multiple_events: Whether Moogsoft Onprem interprets a JSON list as multiple events.
Configure the SSL properties if you want to encrypt communications between the LAM and the REST connection:
- use_ssl: Whether to use SSL certification.
- path_to_ssl_files: Path to the directory that contains the SSL certificates.
- ssl_key_filename: The SSL server key file.
- ssl_cert_filename: The SSL root CA file.
- use_client_certificates: Whether to use SSL client certification.
- client_ca_filename: The SSL client CA file.
- ssl_protocols: Sets the allowed SSL protocols.
Optionally configure the LAM identification and capture logging details:
- name: Maps to $Laminstancename, so that the agent field indicates events Moogsoft Onprem ingests from this LAM.
- capture_log: Name and location of the LAM's capture log file, which it writes to for debugging purposes.
Optionally configure severity conversion. See Severity Reference for further information and "Conversion Rules" in Tokenize Source Event Data for details on conversions in general.
Optionally configure the process logging details:
- configuration_file: Name and location of the LAM's process log configuration file. See Configure Logging for more information.Configure Logging
If you are using a data format with multiple nested fields, see REST LAM Examples for a nested fields example and information on how to handle it.

Example

The following example demonstrates a basic REST LAM configuration that receives messages without authentication or SSL encryption. See REST LAM Examples for some more complex configuration examples.

monitor:
{
    name                          : "REST Lam Monitor",
    class                         : "CRestMonitor",
    port                          : 8888,
    address                       : "0.0.0.0",
    use_ssl                       : false,
    #path_to_ssl_files            : "config",
    #ssl_key_filename             : "server.key",
    #ssl_cert_filename            : "server.pem",
    #use_client_certificates      : false, 
    #client_ca_filename           : "ca.crt",
    #auth_token                   : "my_secret",
    #encrypted_auth_token         : "dfJtTQMGiFHfiq7sCmxguBt6Jv+eytkoiKCquSB/7iWxpgGsG2aez3z2j7SuBtKj",
    #header_auth_token            : "my_secret",
    #encrypted_header_auth_token  : "dfJtTQMGiFHfiq7sCmxguBt6Jv+eytkoiKCquSB/7iWxpgGsG2aez3z2j7SuBtKj",
    #ssl_protocols                : "TLSv1.2",
    authentication_type           : "none",
    #basic_auth_static:     
    #{
        #username                 : "user",
        #password                 : "pass",
        #encrypted_password       : "dfJtTQMGiFHfiq7sCmxguBt6Jv+eytkoiKCquSB/7iWxpgGsG2aez3z2j7SuBtKj"
    #},
    #jwt:                                           
    #{
        #secretKey                : "secret",
        #sub                      : "moogsoft",
        #iss                      : "moogsoft",
        #aud                      : "moogsoft",
        #jti                      : ""
    #},
    authentication_cache          : true,
    accept_all_json               : true,
    lists_contain_multiple_events : true,
    num_threads                   : 5,
    rest_response_mode            : "on_receipt",
    rpc_response_timeout          : 20,
    event_ack_mode                : "queued_for_processing",
},
agent:
{
    name                          : "DATA_SOURCE",
    #capture_log                  : "$MOOGSOFT_HOME/log/data-capture/rest_lam.log"
},
log_config:
{
    configuration_file            : "$MOOGSOFT_HOME/config/logging/rest_lam_log.json"
},

Configure for High Availability

Configure the REST LAM for high availability if required. See High Availability Overview for details.

Configure LAMbot Processing

The REST LAMbot processes and filters events before sending them to the Message Bus. You can customize or bypass this processing if required. You can also load JavaScript files into the LAMbot and execute them.

See LAMbot Configuration for more information. An example REST LAM filter configuration is shown below.

filter:
{
    presend: "RestLam.js"
}

Map LAM Properties

REST messages are mapped to Moogsoft Onprem event fields according to the mapping rules in the REST LAM configuration file.

You can choose to map request headers when the expose_request_headers property is set to true. For example:

{ name: "source", rule: "$moog_request_headers.Origin" }

See the LAM and Integration Reference for more details.

Check the LAM Status

You can use a GET request to check the status of the REST LAM. The request uses the authentication type and header authentication token defined in the REST LAM configuration file. See the authentication_type and header_auth_token properties in the LAM and Integration Reference for more information.

The following examples show the only two possible responses: active and passive.

curl http://localhost:8888 -X GET

Response from an active REST LAM:

{
    "success"     : true,
    "message"     : "Instance is active",
    "statusCode"  : 0
}

Response from an inactive REST LAM:

{
     "success"     : false,
     "message"     : "Instance is passive",
     "statusCode"  : 5004
}

Start and Stop the LAM

Restart the REST LAM to activate any changes you make to the configuration file or LAMbot.

The LAM service name is restlamd.

See Control Moogsoft Onprem Processes for further details.

In this section: