Raritan PX2/PX3 JSON-RPC API

ServerMonitor.idl
1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /*
3 * Copyright 2010 Raritan Inc. All rights reserved.
4 */
5
6 #include <Event.idl>
7 #include <UserEvent.idl>
8
9 /** Server Monitor */
10 module servermon {
11
12 /** Server Monitor Interface */
13 interface ServerMonitor_2_0_1 {
14
15 /**
16 * Server Reachability State
17 */
18 enumeration ServerReachability {
19 WAITING, ///< Waiting for reliable connection
20 REACHABLE, ///< Server is up and running
21 UNREACHABLE, ///< No response from server
22 ERROR ///< Error pinging server (e.g. DNS lookup failure)
23 };
24
25 /**
26 * Server Power Control State
27 */
28 enumeration ServerPowerState {
29 UNKNOWN, ///< Power state currently not known
30 ON, ///< Server power target is on
31 OFF, ///< Server power target is off
32 SHUTTING_DOWN ///< Server is being manually shut down
33 };
34
35 /**
36 * Server Power Control Result
37 */
38 enumeration ServerPowerControlResult {
39 NO_ERROR, ///< No error, operation may still be in progress
40 SHUTDOWN_CMD_FAILED, ///< Error issuing the shutdown command to the server
41 SWITCHING_OFF_FAILED, ///< Switching the outlet or outlet group off failed
42 SWITCHING_ON_FAILED, ///< Switching the outlet or outlet group on failed
43 POWER_CHECK_TIMEOUT ///< Checking if power is off timed out
44 };
45
46 /**
47 * Methods of checking power state
48 */
49 enumeration ServerPowerCheckMethod {
50 TIMER, ///< Server is assumed to be off after a time interval
51 POWER_DROP ///< Server is off if power consumption dropped
52 };
53
54 /**
55 * Settings for controlling and checking power state of the server
56 */
57 structure ServerPowerSettings {
58 boolean enabled; ///< Power control for this server enabled
59 Object target; ///< Target for power control, Outlet or OutletGroup
60 ServerPowerCheckMethod powerCheck; ///< Method to check server's power state
61 double powerThreshold; ///< Active power below this threshold means server is off (in Watt)
62 int timeout; ///< Seconds the power check takes before it ends / times out
63 string shutdownCmd; ///< Shutdown command to send to the server
64 string username; ///< Login used to issue shutdown command to the server
65 string password; ///< Password for the login, write-only, not set if empty
66 int sshPort; ///< SSH port of the server
67 };
68
69 /**
70 * Server Reachability Settings
71 */
72 [sparse_in]
73 structure ServerSettings {
74 string host; ///< Server hostname/IP address
75 boolean enabled; ///< Pinging enabled
76 int pingInterval; ///< Wait time after successful ping
77 int retryInterval; ///< Wait time after unsuccessful ping
78 int activationCount; ///< Minimum number of successful pings to enable feature
79 int failureCount; ///< Number of unsuccessful pings to consider server down
80 int resumeDelay; ///< Wait time before resuming pinging
81 int resumeCount; ///< Number of resumes before going back to WAITING state
82 ServerPowerSettings powerSettings; ///< Settings for controlling the power state of the server
83 };
84
85 /**
86 * Server Reachability Status
87 */
88 structure ServerStatus {
89 ServerPowerState powerState; ///< Power control state
90 ServerPowerControlResult lastPowerControlResult; ///< Last result of a power control operation
91 ServerReachability reachable; ///< Reachability state
92 time lastRequest; ///< Timestamp of last request sent
93 time lastResponse; ///< Timestamp of last response received
94 int requests; ///< Number of requests sent
95 int responses; ///< Number of responses received
96 int failures; ///< Number of consecutive failed pings
97 int resumes; ///< Number of resumes
98 };
99
100 /**
101 * Event: ServerPowerState has changed
102 */
103 valueobject ServerPowerStateEvent extends idl.Event {
104 int id; ///< id of the server entry
105 string host; ///< Server hostname/IP address
106 ServerPowerState oldPowerState; ///< Old power state
107 ServerPowerState newPowerState; ///< New power state
108 };
109
110 /**
111 * Event: A power control operation was initiated
112 */
113 valueobject ServerPowerControlInitiatedEvent extends event.UserEvent {
114 int id; ///< id of the server
115 string host; ///< Server hostname/IP address
116 boolean on; ///< True if server shall be switched on, false otherwise
117 };
118
119 /**
120 * Event: A power control operation was completed
121 */
122 valueobject ServerPowerControlCompletedEvent extends idl.Event {
123 int id; ///< id of the server
124 string host; ///< Server hostname/IP address
125 ServerPowerControlResult result; ///< Result of the power control operation
126 };
127
128 /**
129 * Event: Reachability status for a monitored server has changed or
130 * server continues to be unreachable
131 */
132 valueobject ServerReachabilityEvent extends idl.Event {
133 int id; ///< id of the server entry
134 string host; ///< Server hostname/IP address
135 ServerReachability reachable; ///< Current Reachability state
136 };
137
138 /**
139 * A new server entry was added
140 */
141 valueobject ServerAddedEvent extends event.UserEvent {
142 int id; ///< id of the added server entry
143 ServerSettings settings; ///< Settings of the added server
144 };
145
146 /**
147 * A server entry was changed
148 */
149 valueobject ServerSettingsChangedEvent extends event.UserEvent {
150 int id; ///< id of the server entry
151 ServerSettings oldSettings; ///< Settings before change
152 ServerSettings newSettings; ///< Settings after change
153 };
154
155 /**
156 * A server entry was deleted
157 */
158 valueobject ServerDeletedEvent extends event.UserEvent {
159 int id; ///< id of the deleted server entry
160 };
161
162 /**
163 * Server Entry
164 */
165 structure Server {
166 ServerSettings settings; ///< Server settings
167 ServerStatus status; ///< Server status
168 };
169
170 constant int ERR_NO_SUCH_ID = 1; ///< No such ID
171 constant int ERR_INVALID_SETTINGS = 2; ///< Invalid settings
172 constant int ERR_DUPLICATE_HOSTNAME = 3; ///< Duplicate hostname
173 constant int ERR_MAX_SERVERS_REACHED = 4; ///< Maximum number of server entries
174
175 /**
176 * Add a new server entry.
177 *
178 * @param id New entry id, automatically assigned
179 * @param settings New server settings
180 *
181 * @return 0 if OK
182 * @return 2 if the settings are invalid
183 * @return 3 if an entry for the given hostname exists
184 * @return 4 if the maximum number of servers is reached
185 */
186 int addServer(out int id, in ServerSettings settings);
187
188 /**
189 * Modify an existing server entry.
190 *
191 * @param id Entry id
192 * @param settings New settings
193 *
194 * @return 0 if OK
195 * @return 1 if the entry does not exist
196 * @return 2 if the settings are invalid
197 * @return 3 if an entry for the given hostname exists
198 */
199 int modifyServer(in int id, in ServerSettings settings);
200
201 /**
202 * Delete a server entry.
203 *
204 * @param id Entry id
205 *
206 * @return 0 if OK
207 * @return 1 if the entry does not exist
208 */
209 int deleteServer(in int id);
210
211 /**
212 * Retrieve a server entry (settings and status).
213 *
214 * @param server Server settings and status
215 * @param id Entry id
216 *
217 * @return 0 if OK
218 * @return 1 if the entry does not exist
219 */
220 int getServer(out Server server, in int id);
221
222 /**
223 * Retrieve a list of server entries (settings and status).
224 *
225 * @return Server list
226 */
227 map<int, Server> listServers();
228
229 /**
230 * Control the power state of the outlets the server uses.
231 * Attempting to switch the power off will issue a graceful shutdown of
232 * the server beforehand.
233 *
234 * @param id Entry id
235 * @param on Switch power on if true, off if false
236 *
237 * @return 0 if OK
238 * @return 1 if the entry does not exist
239 * @return 2 if the settings are invalid
240 */
241 int powerControl(in int id, in boolean on);
242
243 };
244
245 }
servermon::ServerMonitor_2_0_1::ServerPowerSettings::timeout
int timeout
Seconds the power check takes before it ends / times out.
Definition: ServerMonitor.idl:62
servermon::ServerMonitor_2_0_1
Server Monitor Interface.
Definition: ServerMonitor.idl:13
servermon::ServerMonitor_2_0_1::ON
Server power target is on.
Definition: ServerMonitor.idl:30
servermon::ServerMonitor_2_0_1::UNREACHABLE
No response from server.
Definition: ServerMonitor.idl:21
servermon::ServerMonitor_2_0_1::on
boolean on
True if server shall be switched on, false otherwise.
Definition: ServerMonitor.idl:116
servermon::ServerMonitor_2_0_1::ServerPowerSettings::sshPort
int sshPort
SSH port of the server.
Definition: ServerMonitor.idl:66
servermon::ServerMonitor_2_0_1::ServerStatus::reachable
ServerReachability reachable
Reachability state.
Definition: ServerMonitor.idl:91
servermon::ServerMonitor_2_0_1::newSettings
ServerSettings newSettings
Settings after change.
Definition: ServerMonitor.idl:152
servermon::ServerMonitor_2_0_1::ServerPowerState
ServerPowerState
Server Power Control State.
Definition: ServerMonitor.idl:28
servermon::ServerMonitor_2_0_1::SWITCHING_OFF_FAILED
Switching the outlet or outlet group off failed.
Definition: ServerMonitor.idl:41
servermon::ServerMonitor_2_0_1::ServerPowerControlResult
ServerPowerControlResult
Server Power Control Result.
Definition: ServerMonitor.idl:38
servermon::ServerMonitor_2_0_1::Server::status
ServerStatus status
Server status.
Definition: ServerMonitor.idl:167
servermon::ServerMonitor_2_0_1::Server::settings
ServerSettings settings
Server settings.
Definition: ServerMonitor.idl:166
servermon::ServerMonitor_2_0_1::ServerSettings::resumeCount
int resumeCount
Number of resumes before going back to WAITING state.
Definition: ServerMonitor.idl:81
servermon::ServerMonitor_2_0_1::ServerStatus::responses
int responses
Number of responses received.
Definition: ServerMonitor.idl:95
servermon::ServerMonitor_2_0_1::ServerPowerSettings::target
Object target
Target for power control, Outlet or OutletGroup.
Definition: ServerMonitor.idl:59
servermon::ServerMonitor_2_0_1::UNKNOWN
Power state currently not known.
Definition: ServerMonitor.idl:29
servermon::ServerMonitor_2_0_1::SHUTDOWN_CMD_FAILED
Error issuing the shutdown command to the server.
Definition: ServerMonitor.idl:40
servermon::ServerMonitor_2_0_1::settings
ServerSettings settings
Settings of the added server.
Definition: ServerMonitor.idl:143
servermon::ServerMonitor_2_0_1::ServerSettings::enabled
boolean enabled
Pinging enabled.
Definition: ServerMonitor.idl:75
servermon::ServerMonitor_2_0_1::result
ServerPowerControlResult result
Result of the power control operation.
Definition: ServerMonitor.idl:125
servermon::ServerMonitor_2_0_1::REACHABLE
Server is up and running.
Definition: ServerMonitor.idl:20
servermon::ServerMonitor_2_0_1::ServerStatus::requests
int requests
Number of requests sent.
Definition: ServerMonitor.idl:94
servermon::ServerMonitor_2_0_1::oldSettings
ServerSettings oldSettings
Settings before change.
Definition: ServerMonitor.idl:151
servermon::ServerMonitor_2_0_1::ServerReachability
ServerReachability
Server Reachability State.
Definition: ServerMonitor.idl:18
servermon::ServerMonitor_2_0_1::host
string host
Server hostname/IP address.
Definition: ServerMonitor.idl:105
servermon::ServerMonitor_2_0_1::ServerSettings::activationCount
int activationCount
Minimum number of successful pings to enable feature.
Definition: ServerMonitor.idl:78
servermon::ServerMonitor_2_0_1::ServerPowerSettings::enabled
boolean enabled
Power control for this server enabled.
Definition: ServerMonitor.idl:58
idl
Basic IDL definitions.
Definition: Event.idl:10
servermon::ServerMonitor_2_0_1::ServerStatus::failures
int failures
Number of consecutive failed pings.
Definition: ServerMonitor.idl:96
servermon::ServerMonitor_2_0_1::reachable
ServerReachability reachable
Current Reachability state.
Definition: ServerMonitor.idl:135
servermon::ServerMonitor_2_0_1::ServerPowerSettings::powerCheck
ServerPowerCheckMethod powerCheck
Method to check server&#39;s power state.
Definition: ServerMonitor.idl:60
servermon::ServerMonitor_2_0_1::ServerSettings::powerSettings
ServerPowerSettings powerSettings
Settings for controlling the power state of the server.
Definition: ServerMonitor.idl:82
servermon::ServerMonitor_2_0_1::Server
Server Entry.
Definition: ServerMonitor.idl:165
servermon::ServerMonitor_2_0_1::TIMER
Server is assumed to be off after a time interval.
Definition: ServerMonitor.idl:50
servermon::ServerMonitor_2_0_1::ServerSettings::pingInterval
int pingInterval
Wait time after successful ping.
Definition: ServerMonitor.idl:76
servermon::ServerMonitor_2_0_1::ServerPowerSettings::username
string username
Login used to issue shutdown command to the server.
Definition: ServerMonitor.idl:64
servermon::ServerMonitor_2_0_1::oldPowerState
ServerPowerState oldPowerState
Old power state.
Definition: ServerMonitor.idl:106
servermon::ServerMonitor_2_0_1::ServerSettings::host
string host
Server hostname/IP address.
Definition: ServerMonitor.idl:74
servermon::ServerMonitor_2_0_1::ServerStatus
Server Reachability Status.
Definition: ServerMonitor.idl:88
servermon::ServerMonitor_2_0_1::ServerStatus::lastPowerControlResult
ServerPowerControlResult lastPowerControlResult
Last result of a power control operation.
Definition: ServerMonitor.idl:90
servermon::ServerMonitor_2_0_1::ServerSettings::failureCount
int failureCount
Number of unsuccessful pings to consider server down.
Definition: ServerMonitor.idl:79
servermon::ServerMonitor_2_0_1::ServerSettings::resumeDelay
int resumeDelay
Wait time before resuming pinging.
Definition: ServerMonitor.idl:80
servermon::ServerMonitor_2_0_1::ServerPowerSettings
Settings for controlling and checking power state of the server.
Definition: ServerMonitor.idl:57
servermon::ServerMonitor_2_0_1::ServerPowerSettings::shutdownCmd
string shutdownCmd
Shutdown command to send to the server.
Definition: ServerMonitor.idl:63
servermon::ServerMonitor_2_0_1::ServerPowerCheckMethod
ServerPowerCheckMethod
Methods of checking power state.
Definition: ServerMonitor.idl:49
servermon::ServerMonitor_2_0_1::ServerStatus::lastRequest
time lastRequest
Timestamp of last request sent.
Definition: ServerMonitor.idl:92
servermon::ServerMonitor_2_0_1::ServerPowerSettings::password
string password
Password for the login, write-only, not set if empty.
Definition: ServerMonitor.idl:65
servermon::ServerMonitor_2_0_1::SWITCHING_ON_FAILED
Switching the outlet or outlet group on failed.
Definition: ServerMonitor.idl:42
servermon::ServerMonitor_2_0_1::newPowerState
ServerPowerState newPowerState
New power state.
Definition: ServerMonitor.idl:107
servermon::ServerMonitor_2_0_1::OFF
Server power target is off.
Definition: ServerMonitor.idl:31
servermon::ServerMonitor_2_0_1::WAITING
Waiting for reliable connection.
Definition: ServerMonitor.idl:19
servermon::ServerMonitor_2_0_1::ServerSettings::retryInterval
int retryInterval
Wait time after unsuccessful ping.
Definition: ServerMonitor.idl:77
servermon::ServerMonitor_2_0_1::ServerStatus::lastResponse
time lastResponse
Timestamp of last response received.
Definition: ServerMonitor.idl:93
servermon::ServerMonitor_2_0_1::ServerPowerSettings::powerThreshold
double powerThreshold
Active power below this threshold means server is off (in Watt)
Definition: ServerMonitor.idl:61
servermon::ServerMonitor_2_0_1::NO_ERROR
No error, operation may still be in progress.
Definition: ServerMonitor.idl:39
servermon::ServerMonitor_2_0_1::ServerStatus::powerState
ServerPowerState powerState
Power control state.
Definition: ServerMonitor.idl:89
servermon::ServerMonitor_2_0_1::ServerSettings
Server Reachability Settings.
Definition: ServerMonitor.idl:73
servermon::ServerMonitor_2_0_1::ServerStatus::resumes
int resumes
Number of resumes.
Definition: ServerMonitor.idl:97
servermon
Server Monitor.
Definition: ServerMonitor.idl:10