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.
- 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.
- 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_cache: Whether to cache the username and password for the current connection when the authentication type is Basic.
- 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.
- 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.
- 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.
- Optionally configure severity conversion. See Severity Reference for further information and "Conversion Rules" in Data Parsing for details on conversions in general.
- 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.
- 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.
40 Comments
Jill Osborne
test
Jill Osborne
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.
Jill Osborne
Scott - Default will be true from 7.0
Jill Osborne
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)
Jill Osborne
This is actually a count of how many events in the message were cached. The same applies for processed and received.
Jill Osborne
There are a few missing:
Jill Osborne
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.
Jill Osborne
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.
Jill Osborne
Scott - There are a few missing codes:
Jill Osborne
This will change to 415 (Unsupported Media Type) in 7.0
Jill Osborne
As accept_all_json now defaults to true, we will have to add "accept_all_json: false" under "monitor" to this conf example.
Jill Osborne
As accept_all_json now defaults to true, we will have to add "accept_all_json: false" under "monitor" to this conf example.
Jill Osborne
As accept_all_json now defaults to true, we will have to add "accept_all_json: false" under "monitor" to this conf example.
Jill Osborne
Scott - When "expose_request_headers" is true, we can also map request headers. For example:
{ name: "source", rule: "$moog_request_headers.Origin" }
Jill Osborne
Scott - These are out of date, you can see all available attributes with the command above.
Jill Osborne
Should be "--log-level"
Charles Smith
funny this would be better called out as SOAP
Charles Smith
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.
Charles Smith
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.
Charles Smith
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
Charles Smith
Where's this documented?
Charles Smith
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.
Charles Smith
This is a pre-requisite
Charles Smith
get rid of this header
Charles Smith
maybe this could be a tip in the intro?
Charles Smith
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.
Charles Smith
Same as above, move this to a reference doc. They could both be part of the same doc.
Charles Smith
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.
Charles Smith
Ugh. This is CURL documentation.
Charles Smith
I don't really see the benefit of this example. Remove.
Charles Smith
I don't really see the benefit of this
Charles Smith
No. This is part of SSL setup. I think get rid of this along with the rest of the example
Charles Smith
get rid of this
Charles Smith
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.
Scott Chamberlin-Wibbeke
This is only used when authentication type is "basic", to cache the basic auth username and password.
Scott Chamberlin-Wibbeke
These aren't authentication related. I'd say they fit best into LAM behaviour.
Scott Chamberlin-Wibbeke
It's when to send a REST response, which could be: on_receipt, event_forwarded or event_processed.
James Scott
you have correctly configured the REST LAM to accept....
James Scott
Why is this on a new line?
Scott Chamberlin-Wibbeke
We also use the header_auth_token if defined in the config.