1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Raritan / Server Technology Xerus™ PDU JSON-RPC API: Event Rules and Actions</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Raritan / Server Technology Xerus™ PDU JSON-RPC API
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Event Rules and Actions </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="md__home_builds_gitlab_builds_QjAyd6bt_0_gitlab_main_firmware_mkdist_tmp_build_pdu_px2_final_documentation_json_rpc_api_eventengine"></a></p>
<p>Event rules and actions are configured with the <b>EventEngine</b> interface at the well-known URI <code>/event_engine</code>. Event rules select a subset of possible events and define one or more actions that should be executed for once for each matching event. Supported event actions include sending SNMP traps or emails, switching outlets or raising alarms.</p>
<h1><a class="anchor" id="autotoc_md121"></a>
Event Rules</h1>
<p>Event rules are managed with the <b>listRules</b>, <b>addRule</b>, <b>modifyRule</b>, <b>enableRule</b>, <b>disableRule</b> and <b>deleteRule</b> methods. Rules connect a trigger condition (a subset of possible events) with one or more actions.</p>
<dl class="section note"><dt>Note</dt><dd>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.</dd></dl>
<p>Events are organized in a hierarchical structure and identified by path. Event IDs can contain dynamic components like user names, outlet numbers or sensor types. Event IDs can contain the wildcard <code>*</code> to match an aribtrary value for a single path element, or end with the <code>**</code> 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.</p>
<p>A few examples for event IDs are:</p>
<ul>
<li><code>Device.SystemStartup</code>: Emitted after the device firmware has booted</li>
<li><code>UserActivity.admin.LoggedIn</code>: The <code>admin</code> user has logged in</li>
<li><code>Inlet.I1.Sensor.current.AboveUpperWarning</code>: The inlet current reading exceeds the upper warning threshold</li>
<li><code>Outlet.*.PowerControl.**</code>: Any outlet has been switched or power-cycled</li>
</ul>
<div class="fragment"><div class="line"><span class="comment"># Python example: Create a rule to invoke user-defined action 'Action_001' when</span></div>
<div class="line"><span class="comment"># any user logs in</span></div>
<div class="line"> </div>
<div class="line"><span class="keyword">from</span> raritan.rpc <span class="keyword">import</span> event</div>
<div class="line"> </div>
<div class="line">event_engine = <a class="code" href="interfaceevent_1_1Engine.html">event.Engine</a>(<span class="stringliteral">"/event_engine"</span>, agent)</div>
<div class="line"> </div>
<div class="line">condition = <a class="code" href="structevent_1_1Engine_1_1Condition.html">event.Engine.Condition</a>(</div>
<div class="line"> negate = <span class="keyword">False</span>, <span class="comment"># ignored</span></div>
<div class="line"> operation = event.Engine.Condition.Op.AND, <span class="comment"># ignored</span></div>
<div class="line"> matchType = event.Engine.Condition.MatchType.ASSERTED, <span class="comment"># only login, not logout</span></div>
<div class="line"> eventId = [ <span class="stringliteral">"UserActivity"</span>, <span class="stringliteral">"*"</span>, <span class="stringliteral">"LoggedIn"</span> ],</div>
<div class="line"> conditions = [] <span class="comment"># ignored</span></div>
<div class="line">)</div>
<div class="line"> </div>
<div class="line">rule = <a class="code" href="structevent_1_1Engine_1_1Rule.html">event.Engine.Rule</a>(</div>
<div class="line"> id = <span class="stringliteral">""</span>, <span class="comment"># assigned upon successful creation</span></div>
<div class="line"> name = <span class="stringliteral">"Any user has logged in"</span>,</div>
<div class="line"> isSystem = <span class="keyword">False</span>,</div>
<div class="line"> isEnabled = <span class="keyword">True</span>,</div>
<div class="line"> isAutoRearm = <span class="keyword">True</span>, <span class="comment"># ignored</span></div>
<div class="line"> hasMatched = <span class="keyword">False</span>, <span class="comment"># ignored</span></div>
<div class="line"> condition = condition,</div>
<div class="line"> actionIds = [ <span class="stringliteral">"Action_001"</span> ],</div>
<div class="line"> arguments = []</div>
<div class="line">)</div>
<div class="line"> </div>
<div class="line">ret, rule_id = event_engine.addRule(rule)</div>
<div class="line"><span class="keywordflow">if</span> ret != 0:</div>
<div class="line"> print(<span class="stringliteral">"Creating rule failed, error code %d"</span> % ret)</div>
<div class="line"><span class="keywordflow">else</span>:</div>
<div class="line"> print(<span class="stringliteral">"Rule created successfully, new rule id: %s"</span> % rule_id)</div>
<div class="ttc" id="ainterfaceevent_1_1Engine_html"><div class="ttname"><a href="interfaceevent_1_1Engine.html">event::Engine</a></div><div class="ttdoc">There is a single event engine instance reachable by a well known reference.</div><div class="ttdef"><b>Definition:</b> EventEngine.idl:53</div></div>
<div class="ttc" id="astructevent_1_1Engine_1_1Condition_html"><div class="ttname"><a href="structevent_1_1Engine_1_1Condition.html">event::Engine::Condition</a></div><div class="ttdoc">Condition is a logical combination of multiple events.</div><div class="ttdef"><b>Definition:</b> EventEngine.idl:210</div></div>
<div class="ttc" id="astructevent_1_1Engine_1_1Rule_html"><div class="ttname"><a href="structevent_1_1Engine_1_1Rule.html">event::Engine::Rule</a></div><div class="ttdoc">A Rule binds an action to a condition.</div><div class="ttdef"><b>Definition:</b> EventEngine.idl:246</div></div>
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md122"></a>
Event Actions</h1>
<p>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 <b>arguments</b> vector.</p>
<div class="fragment"><div class="line"><span class="comment"># Python example: Create action to send out an email notification</span></div>
<div class="line"> </div>
<div class="line"><span class="keyword">from</span> raritan.rpc <span class="keyword">import</span> event</div>
<div class="line"> </div>
<div class="line">event_engine = <a class="code" href="interfaceevent_1_1Engine.html">event.Engine</a>(<span class="stringliteral">"/event_engine"</span>, agent)</div>
<div class="line"> </div>
<div class="line">action = <a class="code" href="structevent_1_1Engine_1_1Action.html">event.Engine.Action</a>(</div>
<div class="line"> id = <span class="stringliteral">""</span>, <span class="comment"># assigned upon successful creation</span></div>
<div class="line"> name = <span class="stringliteral">"Send mail to admin"</span>,</div>
<div class="line"> isSystem = <span class="keyword">False</span>,</div>
<div class="line"> type = <span class="stringliteral">"SendSmtpMessage"</span>,</div>
<div class="line"> arguments = [</div>
<div class="line"> <a class="code" href="structevent_1_1KeyValue.html">event.KeyValue</a>(<span class="stringliteral">"Recipient1"</span>, <span class="stringliteral">"admin@organization.example"</span>),</div>
<div class="line"> <a class="code" href="structevent_1_1KeyValue.html">event.KeyValue</a>(<span class="stringliteral">"OverrideSmtp"</span>, <span class="stringliteral">"0"</span>),</div>
<div class="line"> <a class="code" href="structevent_1_1KeyValue.html">event.KeyValue</a>(<span class="stringliteral">"UseCustomMessage"</span>, <span class="stringliteral">"0"</span>),</div>
<div class="line"> <a class="code" href="structevent_1_1KeyValue.html">event.KeyValue</a>(<span class="stringliteral">"CustomMessage"</span>, <span class="stringliteral">""</span>),</div>
<div class="line"> ]</div>
<div class="line">)</div>
<div class="line"> </div>
<div class="line">ret, action_id = event_engine.addAction(action)</div>
<div class="line"><span class="keywordflow">if</span> ret != 0:</div>
<div class="line"> print(<span class="stringliteral">"Creating action failed, error code %d"</span> % ret)</div>
<div class="line"><span class="keywordflow">else</span>:</div>
<div class="line"> print(<span class="stringliteral">"Action created successfully, new action id: %s"</span> % action_id)</div>
<div class="ttc" id="astructevent_1_1Engine_1_1Action_html"><div class="ttname"><a href="structevent_1_1Engine_1_1Action.html">event::Engine::Action</a></div><div class="ttdoc">An action is a tuple of 'id' (unique within the scope of this event engine), 'name' which is unique a...</div><div class="ttdef"><b>Definition:</b> EventEngine.idl:114</div></div>
<div class="ttc" id="astructevent_1_1KeyValue_html"><div class="ttname"><a href="structevent_1_1KeyValue.html">event::KeyValue</a></div><div class="ttdoc">Helper that is used wherever key/value pairs are required.</div><div class="ttdef"><b>Definition:</b> EventEngine.idl:18</div></div>
</div><!-- fragment --><p>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.</p>
<h2><a class="anchor" id="autotoc_md123"></a>
Execute an Action Group (Action Type: "ActionGroup")</h2>
<p>Executes up to 32 other actions</p>
<ul>
<li><b>Action1</b> .. <b>Action32:</b> IDs of actions to execute</li>
</ul>
<h2><a class="anchor" id="autotoc_md124"></a>
Raise an Alarm (Action Type: "Alarm")</h2>
<p>Supported action types for notification and acknowledgment actions: <code>SendSmtpMessage</code>, <code>SendSyslogMessage</code>, <code>SmsMessage</code>, <code>ExternalBeeper</code>, <code>SwitchBuzzer</code>.</p>
<ul>
<li><b>AlarmNotfActions:</b> IDs of notification actions, separated by semicolons</li>
<li><b>AlarmReNotfEnabled:</b> Enable re-scheduling of alarm notifications ("true"/"false")</li>
<li><b>AlarmReNotfPeriod:</b> Re-scheduling period in minutes (1..1440)</li>
<li><b>AlarmReNotfMaxNum:</b> Re-scheduling limit (1..1000, -1 for unlimited)</li>
<li><b>AlarmAckActions:</b> IDs of acknowledgement notification actions, separated by semicolons</li>
</ul>
<h2><a class="anchor" id="autotoc_md125"></a>
Enable/Disable PDU Load Shedding (Action Type: "SetPduLoadShedding")</h2>
<ul>
<li><b>Operation:</b> "on" to enable load shedding, "off" to disable it.</li>
<li><b>LinkIds:</b> Optional comma-separated list of PDU IDs, defaults to "1" (primary unit) if missing.</li>
</ul>
<h2><a class="anchor" id="autotoc_md126"></a>
Log Event Message (Action Type: "LogEventMessage")</h2>
<ul>
<li><b>UseCustomMessage:</b> "1" to use a custom log message</li>
<li><b>CustomMessage:</b> Custom message text for log message</li>
</ul>
<h2><a class="anchor" id="autotoc_md127"></a>
Send Email (Action Type: "SendSmtpMessage")</h2>
<ul>
<li><b>Recipient:</b> Recipient email address</li>
<li><b>OverrideSmtp:</b> "1" to use custom SMTP server, "0" to use the default server</li>
<li><b>UseCustomMessage:</b> "1" to use a custom mail text</li>
<li><b>CustomMessage:</b> Custom message text for notification message</li>
<li><b>UseCustomMailSubject:</b> "1" to use a custom mail subject</li>
<li><b>CustomMailSubject:</b> Custom subject for notification message</li>
</ul>
<p>The following parameters are only required if <b>OverrideSmtp</b> is set to "1":</p>
<ul>
<li><b>SmtpHost:</b> SMTP server name</li>
<li><b>SmtpPort:</b> SMTP server port</li>
<li><b>SmtpFrom:</b> SMTP sender mail address</li>
<li><b>SmtpRetryCount:</b> Number of sending retries (0..10)</li>
<li><b>SmtpRetryInterval:</b> Retry interval in minutes (1..60)</li>
<li><b>SmtpUseAuth:</b> "1" to use authentication, "0" otherwise</li>
<li><b>SmtpUsername:</b> SMTP user name</li>
<li><b>SmtpPassword:</b> SMTP password</li>
<li><b>SmtpUseTls:</b> "1" to enable SMTP over TLS (StartTLS)</li>
<li><b>SmtpCaCertChain:</b> CA certificate (TLS only)</li>
<li><b>SmtpAllowOffTimeRangeCerts:</b> "1" to allow certificates outside of their validity period</li>
</ul>
<h2><a class="anchor" id="autotoc_md128"></a>
Send SNMP Notification (Action Type: "SendSnmpTrap")</h2>
<ul>
<li><b>SnmpNotfType:</b> Notification type. One of "v2Trap", "v2Inform", "v3Trap", "v3Inform"</li>
<li><b>SnmpTrapDest1:</b> Primary trap destination, format: "<host>:<port>:<community>"</li>
<li><b>SnmpTrapDest2:</b> Optional second destination (SNMPv2 only)</li>
<li><b>SnmpTrapDest3:</b> Optional third destination (SNMPv2 only)</li>
<li><b>SnmpNotfTimeout:</b> Timeout in seconds for SNMPv2/SNMPv3 informs</li>
<li><b>SnmpNotfRetries:</b> Number of retries for SNMPv2/SNMPv3 informs</li>
<li><b>SnmpNotfV3SecName:</b> SNMPv3 security/user name</li>
<li><b>SnmpNotfV3SecLevel:</b> SNMPv3 security level. One of: "noAuthNoPriv", "authNoPriv", "authPriv"</li>
<li><b>SnmpNotfV3AuthProto:</b> SNMPv3 authentication protocol. One of: "md5", "sha", "sha224", "sha256", "sha384", "sha512"</li>
<li><b>SnmpNotfV3AuthKey:</b> SNMPv3 authentication passphrase</li>
<li><b>SnmpNotfV3PrivProto:</b> SNMPv3 privacy protocol. One of: "des", "aes", "aes192", "aes256", "aes192-3des", "aes256-3des"</li>
<li><b>SnmpNotfV3PrivKey:</b> SNMPv3 privacy passphrase</li>
</ul>
<h2><a class="anchor" id="autotoc_md129"></a>
Send Syslog Message (Action Type: "SendSyslogMessage")</h2>
<ul>
<li><b>SyslogServerName:</b> Syslog server name</li>
<li><b>SyslogServerUseTcp:</b> "1" to use TCP instead of UDP</li>
<li><b>SyslogServerUseTls:</b> "1" to use TLS encryption (TCP only)</li>
<li><b>SyslogServerNoBsdCompat:</b> "0" to use legacy BSD protocol (UDP only)</li>
<li><b>SyslogServerPort:</b> Syslog server UDP port</li>
<li><b>SyslogServerTcpPort:</b> Syslog server TCP port</li>
<li><b>SyslogServerTlsPort:</b> Syslog server TCP+TLS port</li>
<li><b>SyslogServerCaCertChain:</b> CA certiicate (TLS only)</li>
<li><b>SyslogServerAllowOffTimeRangeCerts:</b> "1" to allow certificates outside of their validity period</li>
</ul>
<h2><a class="anchor" id="autotoc_md130"></a>
Send SMS Message (Action Type: "SmsMessage")</h2>
<ul>
<li><b>Destination:</b> Recipient phone number</li>
<li><b>UseCustomMessage:</b> "1" to use a custom SMS text</li>
<li><b>CustomMessage:</b> Custom message text for SMS</li>
</ul>
<h2><a class="anchor" id="autotoc_md131"></a>
Internal Beeper (Action Type: "SwitchBuzzer")</h2>
<ul>
<li><b>Operation:</b> "on" to enable beeper, "off" to disable it</li>
<li><b>LinkIds:</b> Optional comma-separated list of PDU IDs, defaults to "1" (primary unit) if missing.</li>
</ul>
<h2><a class="anchor" id="autotoc_md132"></a>
Switch Outlets (Action Type: "SwitchOutlet")</h2>
<ul>
<li><b>Operation:</b> One of "on", "off", "cycle"</li>
<li><p class="startli"><b>OutletIndex:</b> Comma-separated list of outlet indices (0-based) to switch. Items can be prefixed with a link ID (1 for primary unit, 2-8 for link units) to switch outlets in a cascade.</p>
<p class="startli">Example: "0,2,2:4" switches outlets 1 and 3 of the primary unit and outlet 5 of the link unit with link ID 2.</p>
</li>
</ul>
<h2><a class="anchor" id="autotoc_md133"></a>
Switch Peripheral Actuator (Action Type: "SwitchPeripheralActuator")</h2>
<ul>
<li><b>Operation:</b> One of "on", "off", "cycle"</li>
<li><p class="startli"><b>SlotIndex:</b> Comma-separated list of peripheral device slot indices (0-based). Items can be prefixed with a link ID (1 for primary unit, 2-8 for link units) to switch actuators in a cascade.</p>
<p class="startli">Example: "2,2:0,2:8" switches actuator 3 of the primary unit and actuators 1 and 9 of the link unit with linkd ID 2. </p>
</li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Mon Oct 17 2022 00:25:43 for Raritan / Server Technology Xerus™ PDU JSON-RPC API by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1
</small></address>
</body>
</html>
|
