Page tree
Skip to end of metadata
Go to start of metadata

The REST LAM allows Moogsoft AIOps 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 AIOps 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 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 REST LAM Reference for a full description of all properties. Some properties in the file are commented out by default. Uncomment properties to enable them.

  1. Configure the properties for the REST connection:
    • port: Port on the Moogsoft AIOps server that listens for REST messages. Defaults to 8888.
    • address: Address on the Moogsoft AIOps server that listens for REST messages. Default to all interfaces.
    • expose_request_headers: Allows you to include request HTTP headers in Moogsoft AIOps events.

  2. 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.
    • authentication_cacheWhether to cache the username and password for the current connection when the authentication type is Basic.

  3. Configure the LAM behavior:
    • num_threads: Number of worker threads to use.
    • rest_response_mode: When to sends a REST response. See the REST LAM 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 AIOPs interprets a JSON list as multiple events.

  4. 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.
    • 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.
    • ssl_protocols: Sets the allowed SSL protocols. 


  5. Optionally configure the LAM identification and logging details:
    • name: Identifies events the REST LAM sends to the Message Bus.
    • capture_log: Name and location of the LAM's capture log file.
    • configuration_file: Name and location of the LAM's process log configuration file.

  6. Optionally configure severity conversion. See Severity Reference for further information and "Conversion Rules" in Data Parsing for details on conversions in general.

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

  8. Refer to the REST LAM Reference to review the structure of REST LAM response messages and response codes.

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 Integrations HA Configuration 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 AIOps 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 REST LAM 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 REST LAM 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 AIOps Processes for further details.


  • No labels

40 Comments

  1. Scott - As part of INT-3228, we now have a config field "expose_request_headers".  When set to true, the HTTP headers from each request to the REST LAM will be sent as part of the event and to the lambot. I'll add some examples further down with how to use it in the lambot.

  2. Scott - Default will be true from 7.0

  3. Scott - Not sure if worth an example, but as part of INT-3228, we have access to the request headers in the lambot. For example:

    function modifyResponse(inBoundEventData)
    {
    // if you want to modify response data before injecting
    //the same in LAM for tokenizing

    /*inBoundEventData contain below field which can be manipulated as per requirement
    1. responseData - the event data received from the rest server
    2. moog_request_headers - the headers received with the request
    */

    var headers = inBoundEventData.value('moog_request_headers');

    var inputString = inBoundEventData.value('responseData');
    var obj = JSON.parse(inputString);
    if (headers && headers['Origin'] === 'http://example-server.com') {
    obj['source'] = 'example server';
    }
    inBoundEventData.set('responseData', JSON.stringify(obj));

    // returning false or (not returning true) will reject the data
    // and thus no events will be created.
    return true;
    }
  4. This is actually a count of how many events in the message were cached. The same applies for processed and received.

  5. There are a few missing:

    • 202: Accepted - The content was accepted but the processing is not guaranteed
    • 500: Internal server error - An unknown error occurred during processing
    • 503: Service Unavailable - the LAM is passive and not accepting content
  6. Scott - We also support GET, which gives a status of the LAM. I believe there's a ticket to document this already though?

    Also, we accept PUT, it has the same behaviour as POST.

  7. We support all varieties of JSON, XML and YAML content types. For example: application/json, application/activity+json, application/calendar+json, application/xml, text/xml, application/xml-dtd, application/x-yaml, text/yaml, text/x-yaml, etc.

  8. Scott - There are a few missing codes:

    • 3003: Header Authentication Error - the received header auth token did not match the config
    • 3004: JWT Authentication Error - the received JWT did not match the config
    • 5003: Content Cached - given content was accepted but cached, processing is not guaranteed
    • 5004: Passive Instance - LAM is passive and not accepting requests
  9. This will change to 415 (Unsupported Media Type) in 7.0

  10. As accept_all_json now defaults to true, we will have to add "accept_all_json: false" under "monitor" to this conf example.

  11. As accept_all_json now defaults to true, we will have to add "accept_all_json: false" under "monitor" to this conf example.

  12. As accept_all_json now defaults to true, we will have to add "accept_all_json: false" under "monitor" to this conf example.

  13. Scott - When "expose_request_headers" is true, we can also map request headers. For example:

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

  14. Scott - These are out of date, you can see all available attributes with the command above.

  15. Should be "--log-level"

  16. funny this would be better called out as SOAP

  17. This whole section is TOTALLY OUT OF CONTEXT. We should give basic configuration. saying you need to understand the data format that you're sending to the LAM. Then... if you're one of the folks that have a data format with mutliple nested fields, that can be a headache ... see this handy dandy subtopic that tells you all about it and gives you an example and tells you how to resolve it.

  18. Choose one of these examples. Handle it like you are handling Email Lam config. if no auth is the default, i might show basic auth. If we need to keep the JWT auth example, maybe put it in an expander macro.

  19. Even though I don't want to get in the habit of using a ton of expander macros. Because we won't have that option when we migrate to Xyleme

  20. Where's this documented?

  21. we don't need all three of these examples. the description above is adequate. I'd choose a successful response. if you don't get that you have some figuring out to do.

  22. This is a pre-requisite

  23. get rid of this header

  24. maybe this could be a tip in the intro?

  25. This should NOT be a table it is a reference and should just be in a separate doc. This one should be the task of configuring. Then if you run into errors in yr testing refer to that. 

  26. Same as above, move this to a reference doc. They could both be part of the same doc.

  27. This is utterly out of control. Put in 1 example here. If we don't want to toss all the other examples they can go in a subtopic.

  28. Ugh. This is CURL documentation. 

  29. I don't really see the benefit of this example. Remove.

  30. I don't really see the benefit of this

  31. No. This is part of SSL setup. I think get rid of this along with the rest of the example

  32. Optionally put these in a separate Additional examples doc. There is probably a better way to document this than but dumping examples into a wiki. we should think about that separately.

  33. This is only used when authentication type is "basic", to cache the basic auth username and password.

  34. These aren't authentication related. I'd say they fit best into LAM behaviour.

  35. It's when to send a REST response, which could be: on_receipt, event_forwarded or event_processed.


     
  36. you have correctly configured the REST LAM to accept....

  37. Why is this on a new line? 

  38. We also use the header_auth_token if defined in the config.