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

This is a reference for the REST LAM. The REST LAM configuration file is located at $MOOGSOFT_HOME/config/rest_lam.conf

It contains the following sections and properties:

Monitor

name: Name of the LAM.

TypeString
Required: Yes
Default: "Rest Lam Monitor". Do not change.

class: Class of the LAM.

Type: String
Required: Yes
Default: "CRestMonitor". Do not change.

portPort on the Moogsoft AIOps server that listens for REST messages.

Type: Integer
Required: Yes
Default: 8888

addressAddress on the Moogsoft AIOps server that listens for REST messages. 

Type: String
Required: Yes
Default"0.0.0.0" (all interfaces)

expose_request_headersDetermines whether to include request HTTP headers in Moogsoft AIOps events. If set to true, exposed headers are listed under the key moog_request_headers in events.

Type: Boolean
Required
: Yes
Default
: False

use_ssl: Enables Secure Sockets Layer (SSL) certification. If you set this to True, provide SSL certificate details.

Type: Boolean
Required
: Yes
Default
: False

path_to_ssl_files: Path to the directory that contains the SSL certificates. You can use a relative path based upon the $MOOGSOFT_HOME directory. For example the default config indicates $MOOGSOFT_HOME/config.

Type: String
Required: If use_ssl = true
Default"config"

ssl_key_filename: Name of the SSL server key file. 

Type: String
Required: If use_ssl is set to True
Default: N/A

ssl_cert_filename: Name of the SSL root CA file. Must reside in the location contained in path_to_ssl_files.

Type: String
Required: If use_ssl = true
Default: N/A

use_client_certificates: Defines whether to use SSL client certification. 

Type: Boolean
Required
: If use_ssl = true
Default
: False

client_ca_filename: Name of the SSL client CA file. Must reside in the location contained in path_to_ssl_files.

Type: String
Required
: If use_client_certificates = true
Default
: N/A

ssl_protocols: Sets the allowed SSL protocols. 

Type: Array
Required: If protocol = POP3S or IMAPS
Valid protocolsSSLv3, TLSv1, TLSv1.1, TLSv1.2 
Default[ "TLSv1.2" ]

auth_token: Authentication token in the request body. Can only be used when accept_all_json = false. If you define a token you must include it in the body of all requests. You can define auth_token or header_auth_token but not both.

Type: String
Required
: No
Default
: N/A

header_auth_token: Authentication token in the request header. Can only be used when accept_all_json = false. If you define a token you must include it in the header of all requests. You can define auth_token or header_auth_token but not both.

Type: String
Required
: No
Default
: N/A

encrypted_auth_token: Encrypted authentication token in the request body. Can only be used when accept_all_json = false. If you define a token you must include it in the body of all requests. REST LAM can use either auth_token or encrypted_auth_token. The encrypted_auth_token property overrides auth_token.

Type: String
Required
: No
Default
: N/A

encrypted_header_auth_token: Encrypted authentication token in the request header. Can only be used when accept_all_json = false. If you define a token you must include it in the header of all requests. REST LAM can use either header_auth_token or encrypted_header_auth_token. The encrypted_header_auth_token property overrides header_auth_token.

Type: String
Required
: No
Default
: N/A

authentication_type: Defines the HTTP authentication type REST LAM uses. 

Type: String

Required: Yes
One of: basic - REST LAM uses the Graze login.
basic_auth_static - Use the static username and password set in the basic_auth_static property.
none - No authentication.
jwt - JSON Web Token authentication.
Default"none"

basic_auth_static: Defines the username and password used for authentication when authentication_type is set to basic_auth_static.

Type: String
Required
: If authentication_type = basic_auth_static
Default
: N/A

jwt: Sets the claims that are used by the LAM when it creates JSON Web Tokens (JWT).

Type: String
Required: If authentication_type = jwt
Example

jwt:
{
	secretKey	: "secret",
	sub			: "moogsoft",
	iss			: "moogsoft",
	aud			: "moogsoft",
	jti			: ""
}

secretKey: Key the REST LAM uses to validate JSON Web Tokens.

Type: String
Required
: If authentication_type = jwt
Default
: N/A

sub: Subject the REST LAM uses to identify JSON Web Tokens.

Type: String
Required
: No
Default
: N/A

iss: Issuer the REST LAM uses to identify JSON Web Tokens.

Type: String
Required
: No
Default
: N/A

aud: Audience the REST LAM uses to identify JSON Web Tokens.

Type: String
Required
: No
Default
: N/A

jti: Identifier the REST LAM uses to identify JSON Web Tokens.

Type: String
Required
: No
Default
: N/A

authentication_cache: Defines whether a hashed version of a user's password is kept in the internal cache for the duration of the connection. If set to true it enables faster event handling. If set to false users are authenticated with each request. 

Type: Boolean
Required
: If authentication_type = basic
Default
: True

accept_all_json: When set to true, the REST LAM can read and process incoming requests using any valid form of JSON. The REST LAM and LAMbot configurations define the structure of the Moogsoft AIOps event. Set this property to false when you can structure incoming messages in the Moogsoft AIOps format. Using the Moogsoft AIOps format allows you to use the default REST LAM and LAMbot configuration to accept, convert and send incoming requests to the Message Bus. See REST LAM Examples for more information.

Type: Boolean
Required
: Yes
Default
: True

lists_contain_multiple_events: Defines whether a JSON list is interpreted as multiple events. Set to true to allow REST LAM to accept structured events from a third party and convert them into Moogsoft AIOps events.

Type: Boolean
Required
: If accept_all_json = true
Default
: False

num_threads: Number of worker threads to use.

Type: Integer
Required: No
Default: The number of available CPUs, up to a maximum of 8

rest_response_mode: Determines when a REST response is sent for a request.

Type: String
Required: Yes
One of: on_receipt - Send a response when a valid event is received.
event_forwarded - Send a response when an event is sent to the Message Bus.
event_processed - Send a response when an event is processed by the Moogfarmd AlertBuilder Moolet.
Default"event_processed"

rpc_response_timeout: The length of time to wait for a REST response from the Moogfarmd AlertBuilder Moolet, in seconds.

Type: Integer
Required
: If rest_response_mode = event_processed
Default
: 20

event_ack_mode: Determines when Moogfarmd acknowledges events from the REST LAM. 

Type: String
Required: Yes
One ofqueued_for_processing - Acknowledge events when Moogsoft AIOps adds them to the Moolet queue.
event_processed - Acknowledge events when a Moolet processes them.
Default"queued_for_processing"

Agent

name: Identifies events the REST LAM sends to the Message Bus.

Type: String
Required: Yes
Default: "DATA_SOURCE"

log: Location of the REST LAM's capture log file. See Configure Logging for more information.

Type: String
Required: No
Default: N/A

Log Config

configuration_file: File that specifies the configuration of the REST LAM's process log. See Moogsoft AIOps Component Logs for more information.

Type: String
Required: No
Default: "$MOOGSOFT_HOME/config/logging/integrations.log.json"

JSON Responses

REST LAM sends response messages in the form of a JSON object. The response indicates how many events in the message were cached, processed and received.

The REST LAM uses the following standard HTTP return codes to indicate the status of a message. The JSON response object contains the status code and message. 

Response: 200 Ok
Description: REST LAM received and accepted the message. This is not an indication that LAM or LAMbot has property processed the event. Standard LAM log file response messages are issued for error conditions.

Response: 202 Accepted
Description: The content was accepted but processing is not guaranteed.

Response: 400 Bad Request
Description: REST LAM rejected the request due to an invalid request body. 

Response: 401 Unauthorized
DescriptionThe REST LAM configuration file contains an authorization token but there is no matching authorization token in the message header.

Response: 405 Method Not Allowed
DescriptionThe request used an unsupported method. Supported methods are POST, PUT and GET.

Response: 415 Unsupported Media Type
Description: The request used an unsupported media typeJSON, XML and YAML are supported in the Content-Type header.

Response: 500 Internal Server Error
Description: An unknown error occurred during processing.

Response: 503 Service Unavailable
Description: REST LAM is passive and not accepting requests.


In the event of an error, REST LAM provides the following REST response codes indicating the status of the request:

Response: 1000 General Error
DescriptionThe request could not proceed and failed in a way that was unexpected.

Response: 3001 Security Authentication Error
Description: There was a failure in basic authorization or the body authorization token check failed.

Response: 3004 JWT Authentication Error
Description: The received JSON Web Token did not match the configuration.

Response: 4000 General Method Error
Description: There was an error with the method.

Response: 4001 Method Not Supported
Description: The HTTP method is not supported.

Response: 5001 Content Not Supported
Description: The content type is not supported.

Response: 5002 Content Decoding Error
Description: The content could not be decoded.

Response: 5003 Content Cached
Description: The content was accepted and cached. Processing is not guaranteed.

Response: 5004 Passive Instance
Description: REST LAM is passive and not accepting requests.


  • No labels

10 Comments

  1. This field will only be used if we're using the Moog protocol (accept_all_json is false).

  2. This should probably be grouped with the other SSL fields

  3. It could also be XML or YAML. So, I would say something like "invalid request body" instead.

  4. Might be worth mentioning that only JSON, XML and YAML media types are supported in the Content-Type header?

  5. We don't use 3000 anymore, but we have 3001, which is a Security Authentication Error for when the basic auth or body auth token check fails.

  6. We don't return this anymore

  7. Should we add a link to what these are? Or spell out what JWT stands for? 

  8. Not sure we can link to these as they are Mozilla's documentation... technically open-source but maybe check with Charles/ Monique?