LAM and Integration Reference

This is a reference for the LAMs and UI integrations. The LAM configuration files are located at $MOOGSOFT_HOME/config/. See the individual LAM and integration configuration pages for the names of the files.

The configuration options for LAMs contain the following sections and properties. Some of these properties are configurable in UI integrations.

Monitor

name

Name of the LAM.

Type

String

Required

Yes

Default

Each LAM configuration contains a default name. Do not change this.

class

Class of the LAM.

Type

String

Required

Yes

Default

Each LAM configuration contains a default class. Do not change this.

expose_request_headers

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

Type

Boolean

Required

No

Default

false

use_ssl

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

Type

Boolean

Required

No

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

Yes, if use_ssl = true

Default

"config"

ssl_key_filename

Name of the SSL server key file.

Type

String

Required

Yes, 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

Yes, if use_ssl = true

Default

N/A

use_client_certificates

Defines whether to use SSL client certification.

Type

Boolean

Required

Yes, 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

Yes, if use_ssl = true

Default

N/A

ssl_protocols

Sets the allowed SSL protocols.

Type

Array

Required

Yes, if protocol is set to POP3S or IMAPS

Default

[ "TLSv1.2" ]

Valid Values

SSLv3, TLSv1, TLSv1.1, 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. 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. Overrides header_auth_token.

Type

String

Required

No

Default

N/A

authentication_type

Defines the authentication type the LAM uses.

Type

String

Required

Yes

Default

Varies. See the individual LAM and integration configuration documents.

Valid Values

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

basic_auth_static

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

Type

String

Required

Yes, if authentication_type = basic_auth_static

Default

N/A

jwt

Defines the claims the LAM uses when it creates JSON Web Tokens (JWT).

Type

String

Required

Yes, if authentication_type = jwt

Default

N/A

Example:

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

secretKey

Key the LAM uses to validate JSON Web Tokens.

Type

String

Required

Yes, if authentication_type = jwt

Default

N/A

sub

Subject the LAM uses to identify JSON Web Tokens.

Type

String

Required

No

Default

N/A

iss

Issuer the LAM uses to identify JSON Web Tokens.

Type

String

Required

No

Default

N/A

aud

Audience the LAM uses to identify JSON Web Tokens.

Type

String

Required

No

Default

N/A

jti

Identifier the LAM uses to iMoogsoft Enterprisedentify 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

Yes, if authentication_type = basic

Default

true

accept_all_json

When set to true, the LAM can read and process incoming requests using any valid form of JSON. The LAM and LAMbot configurations define the structure of the event. Set this property to false when you can structure incoming messages in the Moogsoft Enterprise format. Using the Moogsoft Enterprise format allows you to use the default 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

No

Default

true

lists_contain_multiple_events

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

Type

Boolean

Required

Yes, if accept_all_json = true

Default

false

num_threads

Number of worker threads to use for processing events. If you have a large number of events and javascript logic, increase the number of threads. Also increase the thread count if a queue builds up in the LAMs. You can use the heartbeat monitor or Graze API to check the queue size.

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

Default

event_processed

Valid Values

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

rpc_response_timeout

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

Type

Integer

Required

Yes, if rest_response_mode = event_processed

Default

20

event_ack_mode

Determines when Moogfarmd acknowledges events from the LAM.

Type

String

Required

Yes

Default

"queued_for_processing"

Valid Values

  • queued_for_processing: Acknowledge events when Moogsoft Enterprise adds them to the Moolet queue.

  • event_processed: Acknowledge events when a Moolet processes them.

request_interval

Length of time to wait between requests, in seconds. Can be overridden by request_interval in individual targets.

Type

Integer

Required

No

Default

60

max_retries

Number of times the LAM attempts to reconnect after connection failure. Used in conjunction with retry_interval.

Type

Integer

Required

No

Default

-1 (infinite retries)

retry_interval

Length of time to wait between reconnection attempts, in seconds. Used in conjunction with max_retries.

Type

Integer

Required

No

Default

60

timeout

Length of time to wait before halting a connection or read attempt, in seconds.

Type

Integer

Required

No

Default

120

max_lookback

Period of time for which to recover missed events, in seconds, when the LAM re-establishes a connection after a failure.

Type

Integer

Required

No

Default

-1 (recover all events since the last successful poll)

retry_recovery

Object containing properties which allow you to specify how the LAM recovers events that were missed during a connection outage. Comment out this object to recover all missed events with no imposed waiting time.

Type

Object

Required

No

Default

N/A

recovery_interval

Length of time to wait between requests, in seconds, when the LAM re-establishes a connection after a failure.

Type

Integer

Required

No

Default

20

disable_certificate_validation

Specifies whether to disable SSL certificate validation. If set to true the data transmission between Moogsoft Enterprise and the external system is not protected by the encryption protocol. Works on chains that consist of more than one certificate.

Type

Boolean

Required

No

Default

false

proxy

Specifies connection details for a proxy server if you want to connect to the external system through a proxy. To use, uncomment the proxy section of the file and define the host, user, port, and password or encrypted password for the proxy. Not all properties are configurable in every LAM and integration.

Type

String

Required

No

Default

N/A

targets

This property is available in multi-target LAMs. It is a top-level container defining one or more target event sources. You can specify the configuration for each target. If you don't specify a request_interval the target uses the globally defined interval. See Tokenize Source Event Data for more information.Data Parsing

Type

JSON Object

Required

Yes

Default

N/A

requests_overlap

If events meet the overlap_identity_fields matching criteria during this interval (in seconds), they are not treated as duplicates. Used to ensure that Moogsoft Enterprise does not miss valid events.

Type

Integer

Required

No

Default

N/A

overlap_identity_fields

A list of payload tokens the LAM uses to identify duplicate events when the source returns all open events and not just updated events. After the requests_overlapperiod the LAM treats events with the same overlap identity fields as duplicate events. The LAM identifies duplicates for each payload event in the previous request only. Identification is based on the token names of the returned payload, not the mapped names. For example, including $signature refers to this value in the payload, not event.value("signature").

Type

String

Required

Yes, if requests_overlap is enabled

Default

N/A

Datadog Polling LAM Example:

overlap_identity_fields: [ "id", "alert_type", "priority" ]

SevOne LAM Example:

overlap_identity_fields: [ "id", "severity", "closed", "number" ]

virtual_host

Hostname of a RabbitMQ virtual host.

Type

String

Required

Yes

Default

emc.smarts.notifications

Email

folder_path

Name of the folder containing the email messages.

Type

String

Required

Yes

Default

INBOX

retrieve

Specifies whether to receive all email messages or only unread messages.

Type

String

Required

Yes

Default

UNREAD

Valid Values

UNREAD, ALL

retrieve_filter

Specifies one or more filters to limit the email messages to retrieve. The LAM concatenates field-level filters with the AND operator. For example, if you set a "To" filter and a "From" filter, a message must match both fields to meet the filter criteria. For each field, you can specify multiple values that the LAM joins with an OR operator. For example, if you set two email addresses for the "To" field, the message can match one or the other to meet the filter criteria.

Type

String

Required

No

Default

N/A

Example:

{
    to              : ["support@moogsoft.com", "support1@moogsoft.com"],
    from            : ["customer@abc.com", "customer@xyz.com"],
    #recipient      : [],
    subject         : ["Alert", "Event"],
    #body           : ""
}

to

A list of email addresses used to filter the "To" field in email messages. If multiple adresses are set, the email is retrieved if any of them match the "To" address.

Type

String

Required

No

Default

N/A

from

A list of email address used to filter the "From" field in email messages. If multiple addresses are set, the email is returned if any of them match the "From" address.

Type

String

Required

No

Default

N/A

recipient

A list of email addresses used to filter the "To", "CC" and "BCC" fields in email messages. If multiple addresses are set, the email is returned if any of them match the address in "To", "CC" or "BCC".

Type

String

Required

No

Default

N/A

subject

A list of strings used to filter the subject field in email messages. The email is returned if any of the strings are found in the subject. The matching is case-insensitive.

Type

String

Required

No

Default

N/A

body

A string used to filter the body in email messages. The email is returned if the string is found in the body. The matching is case-insensitive.

Type

String

Required

No

Default

N/A

mark_as_read

Marks unread emails as read.

Type

Boolean

Required

Yes, if retrieve is set to UNREAD

Default

false

delete_on_retrieve

Specifies whether to delete email messages on retrieval.

Type

Boolean

Required

No

Default

false

remove_html_tags

Whether to remove HTML tags from email messages.

Type

Boolean

Required

No

Default

true

treat_body_as_json

Decodes the email body into a JSON object and makes it available for mapping under the $body key. Set to true if the body of retrieved email messages contain JSON objects only.

Type

Boolean

Required

No

Default

false

Agent

name

Identifies events the LAM sends to the Message Bus.

Type

String

Required

Yes

Default

"DATA_SOURCE"

log

Location of the 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 LAM's process log. See Configure Logging for more information.

Type

String

Required

No

Default

$MOOGSOFT_HOME/config/logging/integrations.log.json"