Legrand / Raritan Xerus™ JSON-RPC API for Remote Access Devices like KX4-101, KX3G2

Loading...
Searching...
No Matches
Event Rules and Actions

Event rules and actions are configured with the EventEngine interface at the well-known URI `/event_engine`. Event rules select a subset of possible events and define one or more actions that should be executed once for each matching event. Supported event actions include sending SNMP traps or emails, or creating log messages.

# Event Rules

Event rules are managed with the listRules, addRule, modifyRule, enableRule, disableRule and deleteRule methods. Rules connect a trigger condition (a subset of possible events) with one or more actions.

Note
  The IDL interface was designed for defining complex rules that perform logical operations to combine multiple event conditions. However, as of now this is not supported by the firmware. Event rules can only have a single trigger conditions, possibly using wildcards to select entire subtrees.

Events are organized in a hierarchical structure and identified by path. Event IDs can contain dynamic components like user names or port IDs. Event IDs can contain the wildcard `*` to match an arbitrary value for a single path element, or end with the `**` wildcard to select a complete subtree of events. The list of supported event conditions strongly depends on the device model and configuration. The easiest way to find the event ID for a particular event is to configure a rule in the web GUI and then inspect it with JSON-RPC.

A few examples for event IDs are:

- `Device.SystemStartup`: Emitted after the device firmware has booted
- `UserActivity.admin.LoggedIn`: The `admin` user has logged in
- `Kvmport.**`: Any event related to a KVM port

# Python example: Create a rule to invoke user-defined action 'Action_001' when
# any user logs in
from xeruskvm.rpc import event
event_engine = event.Engine("/event_engine", agent)
condition = event.Engine.Condition(
negate = False, # ignored
operation = event.Engine.Condition.Op.AND, # ignored
matchType = event.Engine.Condition.MatchType.ASSERTED, # only login, not logout
eventId = [ "UserActivity", "*", "LoggedIn" ],
conditions = [] # ignored
)
rule = event.Engine.Rule(
id = "", # assigned upon successful creation
name = "Any user has logged in",
isSystem = False,
isEnabled = True,
isAutoRearm = True, # ignored
hasMatched = False, # ignored
condition = condition,
actionIds = [ "Action_001" ],
arguments = []
)
ret, rule_id = event_engine.addRule(rule)
if ret != 0:
print("Creating rule failed, error code %d" % ret)
else:
print("Rule created successfully, new rule id: %s" % rule_id)
event::Engine
There is a single event engine instance reachable by a well known reference.
Definition EventEngine.idl:53
event::Engine::Condition
Condition is a logical combination of multiple events.
Definition EventEngine.idl:211
event::Engine::Rule
A Rule binds an action to a condition.
Definition EventEngine.idl:247

# Event Actions

Event actions define what to do in case an emitted event matches a rule. There are many types of actions, all with specific configuration parameters. Action parameters are specified as key-value pairs in the arguments vector.

# Python example: Create action to send out an email notification
from xeruskvm.rpc import event
event_engine = event.Engine("/event_engine", agent)
action = event.Engine.Action(
id = "", # assigned upon successful creation
name = "Send mail to admin",
isSystem = False,
type = "SendSmtpMessage",
arguments = [
event.KeyValue("Recipient1", "admin@organization.example"),
event.KeyValue("OverrideSmtp", "0"),
event.KeyValue("UseCustomMessage", "0"),
event.KeyValue("CustomMessage", ""),
]
)
ret, action_id = event_engine.addAction(action)
if ret != 0:
print("Creating action failed, error code %d" % ret)
else:
print("Action created successfully, new action id: %s" % action_id)
event::Engine::Action
An action is a tuple of 'id' (unique within the scope of this event engine), 'name' which is unique a...
Definition EventEngine.idl:115
event::KeyValue
Helper that is used wherever key/value pairs are required.
Definition EventEngine.idl:18

The following sections list the most important action types and their parameters. The list is not complete; check the web GUI to see all supported actions.

## Execute an Action Group (Action Type: "ActionGroup")

Executes up to 32 other actions

- Action1 .. Action32: IDs of actions to execute

## Log Event Message (Action Type: "LogEventMessage")

- UseCustomMessage: "1" to use a custom log message
- CustomMessage: Custom message text for log message

## Send Email (Action Type: "SendSmtpMessage")

- Recipient: Recipient email address
- OverrideSmtp: "1" to use custom SMTP server, "0" to use the default server
- UseCustomMessage: "1" to use a custom mail text
- CustomMessage: Custom message text for notification message
- UseCustomMailSubject: "1" to use a custom mail subject
- CustomMailSubject: Custom subject for notification message

The following parameters are only required if OverrideSmtp is set to "1":

- SmtpHost: SMTP server name
- SmtpPort: SMTP server port
- SmtpFrom: SMTP sender mail address
- SmtpRetryCount: Number of sending retries (0..10)
- SmtpRetryInterval: Retry interval in minutes (1..60)
- SmtpUseAuth: "1" to use authentication, "0" otherwise
- SmtpUsername: SMTP user name
- SmtpPassword: SMTP password
- SmtpUseTls: "1" to enable SMTP over TLS (StartTLS)
- SmtpCaCertChain: CA certificate (TLS only)
- SmtpAllowOffTimeRangeCerts: "1" to allow certificates outside of their validity period

## Send SNMP Notification (Action Type: "SendSnmpTrap")

- SnmpNotfType: Notification type. One of "v2Trap", "v2Inform", "v3Trap", "v3Inform"
- SnmpTrapDest1: Primary trap destination, format: "<host>:<port>:<community>"
- SnmpTrapDest2: Optional second destination (SNMPv2 only)
- SnmpTrapDest3: Optional third destination (SNMPv2 only)
- SnmpNotfTimeout: Timeout in seconds for SNMPv2/SNMPv3 informs
- SnmpNotfRetries: Number of retries for SNMPv2/SNMPv3 informs
- SnmpNotfV3SecName: SNMPv3 security/user name
- SnmpNotfV3SecLevel: SNMPv3 security level. One of: "noAuthNoPriv", "authNoPriv", "authPriv"
- SnmpNotfV3AuthProto: SNMPv3 authentication protocol. One of: "md5", "sha", "sha224", "sha256", "sha384", "sha512"
- SnmpNotfV3AuthKey: SNMPv3 authentication passphrase
- SnmpNotfV3PrivProto: SNMPv3 privacy protocol. One of: "des", "aes", "aes192", "aes256", "aes192-3des", "aes256-3des"
- SnmpNotfV3PrivKey: SNMPv3 privacy passphrase

## Send Syslog Message (Action Type: "SendSyslogMessage")

- SyslogServerName: Syslog server name
- SyslogServerUseTcp: "1" to use TCP instead of UDP
- SyslogServerUseTls: "1" to use TLS encryption (TCP only)
- SyslogServerNoBsdCompat: "0" to use legacy BSD protocol (UDP only)
- SyslogServerPort: Syslog server UDP port
- SyslogServerTcpPort: Syslog server TCP port
- SyslogServerTlsPort: Syslog server TCP+TLS port
- SyslogServerCaCertChain: CA certiicate (TLS only)
- SyslogServerAllowOffTimeRangeCerts: "1" to allow certificates outside of their validity period