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

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