Legrand / Raritan / Server Technology Xerus™ JSON-RPC API

Loading...
Searching...
No Matches
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 */
10module servermon {
11
12 /** Server Monitor Interface */
13 interface ServerMonitor {
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; ///< UNIX timestamp (UTC) of last request sent
93 time lastResponse; ///< UNIX timestamp (UTC) 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 * @note The ServerSettings structure can be "sparse"; fields missing in
187 * the JSON representation will be set to default values.
188 */
189 int addServer(out int id, in ServerSettings settings);
190
191 /**
192 * Modify an existing server entry.
193 *
194 * @param id Entry id
195 * @param settings New settings
196 *
197 * @return 0 if OK
198 * @return 1 if the entry does not exist
199 * @return 2 if the settings are invalid
200 * @return 3 if an entry for the given hostname exists
201 *
202 * @note The ServerSettings structure can be "sparse"; fields missing in
203 * the JSON representation will remain unchanged.
204 */
205 int modifyServer(in int id, in ServerSettings settings);
206
207 /**
208 * Delete a server entry.
209 *
210 * @param id Entry id
211 *
212 * @return 0 if OK
213 * @return 1 if the entry does not exist
214 */
215 int deleteServer(in int id);
216
217 /**
218 * Retrieve a server entry (settings and status).
219 *
220 * @param server Server settings and status
221 * @param id Entry id
222 *
223 * @return 0 if OK
224 * @return 1 if the entry does not exist
225 */
226 int getServer(out Server server, in int id);
227
228 /**
229 * Retrieve a list of server entries (settings and status).
230 *
231 * @return Server list
232 */
233 map<int, Server> listServers();
234
235 /**
236 * Control the power state of the outlets the server uses.
237 * Attempting to switch the power off will issue a graceful shutdown of
238 * the server beforehand.
239 *
240 * @param id Entry id
241 * @param on Switch power on if true, off if false
242 *
243 * @return 0 if OK
244 * @return 1 if the entry does not exist
245 * @return 2 if the settings are invalid
246 */
247 int powerControl(in int id, in boolean on);
248
249 };
250
251}
servermon::ServerMonitor
Server Monitor Interface.
Definition ServerMonitor.idl:13
servermon::ServerMonitor::ServerPowerState
ServerPowerState
Server Power Control State.
Definition ServerMonitor.idl:28
servermon::ServerMonitor::OFF
@ OFF
Server power target is off.
Definition ServerMonitor.idl:31
servermon::ServerMonitor::UNKNOWN
@ UNKNOWN
Power state currently not known.
Definition ServerMonitor.idl:29
servermon::ServerMonitor::ON
@ ON
Server power target is on.
Definition ServerMonitor.idl:30
servermon::ServerMonitor::ServerReachability
ServerReachability
Server Reachability State.
Definition ServerMonitor.idl:18
servermon::ServerMonitor::REACHABLE
@ REACHABLE
Server is up and running.
Definition ServerMonitor.idl:20
servermon::ServerMonitor::WAITING
@ WAITING
Waiting for reliable connection.
Definition ServerMonitor.idl:19
servermon::ServerMonitor::UNREACHABLE
@ UNREACHABLE
No response from server.
Definition ServerMonitor.idl:21
servermon::ServerMonitor::deleteServer
int deleteServer(in int id)
Delete a server entry.
servermon::ServerMonitor::modifyServer
int modifyServer(in int id, in ServerSettings settings)
Modify an existing server entry.
servermon::ServerMonitor::ServerPowerControlResult
ServerPowerControlResult
Server Power Control Result.
Definition ServerMonitor.idl:38
servermon::ServerMonitor::SWITCHING_ON_FAILED
@ SWITCHING_ON_FAILED
Switching the outlet or outlet group on failed.
Definition ServerMonitor.idl:42
servermon::ServerMonitor::SWITCHING_OFF_FAILED
@ SWITCHING_OFF_FAILED
Switching the outlet or outlet group off failed.
Definition ServerMonitor.idl:41
servermon::ServerMonitor::SHUTDOWN_CMD_FAILED
@ SHUTDOWN_CMD_FAILED
Error issuing the shutdown command to the server.
Definition ServerMonitor.idl:40
servermon::ServerMonitor::NO_ERROR
@ NO_ERROR
No error, operation may still be in progress.
Definition ServerMonitor.idl:39
servermon::ServerMonitor::ServerPowerCheckMethod
ServerPowerCheckMethod
Methods of checking power state.
Definition ServerMonitor.idl:49
servermon::ServerMonitor::TIMER
@ TIMER
Server is assumed to be off after a time interval.
Definition ServerMonitor.idl:50
servermon::ServerMonitor::powerControl
int powerControl(in int id, in boolean on)
Control the power state of the outlets the server uses.
servermon::ServerMonitor::getServer
int getServer(out Server server, in int id)
Retrieve a server entry (settings and status).
servermon::ServerMonitor::listServers
map< int, Server > listServers()
Retrieve a list of server entries (settings and status).
servermon::ServerMonitor::addServer
int addServer(out int id, in ServerSettings settings)
Add a new server entry.
idl
Basic IDL definitions.
Definition Event.idl:10
servermon
Server Monitor.
Definition ServerMonitor.idl:10
idl::Event
Common base for all events.
Definition Event.idl:13
servermon::ServerMonitor::ServerAddedEvent
A new server entry was added.
Definition ServerMonitor.idl:141
servermon::ServerMonitor::ServerAddedEvent::settings
ServerSettings settings
Settings of the added server.
Definition ServerMonitor.idl:143
servermon::ServerMonitor::ServerAddedEvent::id
int id
id of the added server entry
Definition ServerMonitor.idl:142
servermon::ServerMonitor::ServerDeletedEvent
A server entry was deleted.
Definition ServerMonitor.idl:158
servermon::ServerMonitor::ServerDeletedEvent::id
int id
id of the deleted server entry
Definition ServerMonitor.idl:159
servermon::ServerMonitor::ServerPowerControlCompletedEvent
Event: A power control operation was completed.
Definition ServerMonitor.idl:122
servermon::ServerMonitor::ServerPowerControlCompletedEvent::result
ServerPowerControlResult result
Result of the power control operation.
Definition ServerMonitor.idl:125
servermon::ServerMonitor::ServerPowerControlCompletedEvent::id
int id
id of the server
Definition ServerMonitor.idl:123
servermon::ServerMonitor::ServerPowerControlCompletedEvent::host
string host
Server hostname/IP address.
Definition ServerMonitor.idl:124
servermon::ServerMonitor::ServerPowerControlInitiatedEvent
Event: A power control operation was initiated.
Definition ServerMonitor.idl:113
servermon::ServerMonitor::ServerPowerControlInitiatedEvent::id
int id
id of the server
Definition ServerMonitor.idl:114
servermon::ServerMonitor::ServerPowerControlInitiatedEvent::on
boolean on
True if server shall be switched on, false otherwise.
Definition ServerMonitor.idl:116
servermon::ServerMonitor::ServerPowerControlInitiatedEvent::host
string host
Server hostname/IP address.
Definition ServerMonitor.idl:115
servermon::ServerMonitor::ServerPowerSettings
Settings for controlling and checking power state of the server.
Definition ServerMonitor.idl:57
servermon::ServerMonitor::ServerPowerSettings::powerCheck
ServerPowerCheckMethod powerCheck
Method to check server's power state.
Definition ServerMonitor.idl:60
servermon::ServerMonitor::ServerPowerSettings::username
string username
Login used to issue shutdown command to the server.
Definition ServerMonitor.idl:64
servermon::ServerMonitor::ServerPowerSettings::sshPort
int sshPort
SSH port of the server.
Definition ServerMonitor.idl:66
servermon::ServerMonitor::ServerPowerSettings::powerThreshold
double powerThreshold
Active power below this threshold means server is off (in Watt)
Definition ServerMonitor.idl:61
servermon::ServerMonitor::ServerPowerSettings::password
string password
Password for the login, write-only, not set if empty.
Definition ServerMonitor.idl:65
servermon::ServerMonitor::ServerPowerSettings::target
Object target
Target for power control, Outlet or OutletGroup.
Definition ServerMonitor.idl:59
servermon::ServerMonitor::ServerPowerSettings::timeout
int timeout
Seconds the power check takes before it ends / times out.
Definition ServerMonitor.idl:62
servermon::ServerMonitor::ServerPowerSettings::enabled
boolean enabled
Power control for this server enabled.
Definition ServerMonitor.idl:58
servermon::ServerMonitor::ServerPowerSettings::shutdownCmd
string shutdownCmd
Shutdown command to send to the server.
Definition ServerMonitor.idl:63
servermon::ServerMonitor::ServerPowerStateEvent
Event: ServerPowerState has changed.
Definition ServerMonitor.idl:103
servermon::ServerMonitor::ServerPowerStateEvent::id
int id
id of the server entry
Definition ServerMonitor.idl:104
servermon::ServerMonitor::ServerPowerStateEvent::oldPowerState
ServerPowerState oldPowerState
Old power state.
Definition ServerMonitor.idl:106
servermon::ServerMonitor::ServerPowerStateEvent::host
string host
Server hostname/IP address.
Definition ServerMonitor.idl:105
servermon::ServerMonitor::ServerPowerStateEvent::newPowerState
ServerPowerState newPowerState
New power state.
Definition ServerMonitor.idl:107
servermon::ServerMonitor::ServerReachabilityEvent
Event: Reachability status for a monitored server has changed or server continues to be unreachable.
Definition ServerMonitor.idl:132
servermon::ServerMonitor::ServerReachabilityEvent::reachable
ServerReachability reachable
Current Reachability state.
Definition ServerMonitor.idl:135
servermon::ServerMonitor::ServerReachabilityEvent::host
string host
Server hostname/IP address.
Definition ServerMonitor.idl:134
servermon::ServerMonitor::ServerReachabilityEvent::id
int id
id of the server entry
Definition ServerMonitor.idl:133
servermon::ServerMonitor::ServerSettingsChangedEvent
A server entry was changed.
Definition ServerMonitor.idl:149
servermon::ServerMonitor::ServerSettingsChangedEvent::newSettings
ServerSettings newSettings
Settings after change.
Definition ServerMonitor.idl:152
servermon::ServerMonitor::ServerSettingsChangedEvent::oldSettings
ServerSettings oldSettings
Settings before change.
Definition ServerMonitor.idl:151
servermon::ServerMonitor::ServerSettingsChangedEvent::id
int id
id of the server entry
Definition ServerMonitor.idl:150
servermon::ServerMonitor::ServerSettings
Server Reachability Settings.
Definition ServerMonitor.idl:73
servermon::ServerMonitor::ServerSettings::enabled
boolean enabled
Pinging enabled.
Definition ServerMonitor.idl:75
servermon::ServerMonitor::ServerSettings::pingInterval
int pingInterval
Wait time after successful ping.
Definition ServerMonitor.idl:76
servermon::ServerMonitor::ServerSettings::activationCount
int activationCount
Minimum number of successful pings to enable feature.
Definition ServerMonitor.idl:78
servermon::ServerMonitor::ServerSettings::powerSettings
ServerPowerSettings powerSettings
Settings for controlling the power state of the server.
Definition ServerMonitor.idl:82
servermon::ServerMonitor::ServerSettings::retryInterval
int retryInterval
Wait time after unsuccessful ping.
Definition ServerMonitor.idl:77
servermon::ServerMonitor::ServerSettings::resumeDelay
int resumeDelay
Wait time before resuming pinging.
Definition ServerMonitor.idl:80
servermon::ServerMonitor::ServerSettings::resumeCount
int resumeCount
Number of resumes before going back to WAITING state.
Definition ServerMonitor.idl:81
servermon::ServerMonitor::ServerSettings::failureCount
int failureCount
Number of unsuccessful pings to consider server down.
Definition ServerMonitor.idl:79
servermon::ServerMonitor::ServerSettings::host
string host
Server hostname/IP address.
Definition ServerMonitor.idl:74
servermon::ServerMonitor::ServerStatus
Server Reachability Status.
Definition ServerMonitor.idl:88
servermon::ServerMonitor::ServerStatus::lastResponse
time lastResponse
UNIX timestamp (UTC) of last response received.
Definition ServerMonitor.idl:93
servermon::ServerMonitor::ServerStatus::failures
int failures
Number of consecutive failed pings.
Definition ServerMonitor.idl:96
servermon::ServerMonitor::ServerStatus::powerState
ServerPowerState powerState
Power control state.
Definition ServerMonitor.idl:89
servermon::ServerMonitor::ServerStatus::resumes
int resumes
Number of resumes.
Definition ServerMonitor.idl:97
servermon::ServerMonitor::ServerStatus::reachable
ServerReachability reachable
Reachability state.
Definition ServerMonitor.idl:91
servermon::ServerMonitor::ServerStatus::responses
int responses
Number of responses received.
Definition ServerMonitor.idl:95
servermon::ServerMonitor::ServerStatus::lastPowerControlResult
ServerPowerControlResult lastPowerControlResult
Last result of a power control operation.
Definition ServerMonitor.idl:90
servermon::ServerMonitor::ServerStatus::requests
int requests
Number of requests sent.
Definition ServerMonitor.idl:94
servermon::ServerMonitor::ServerStatus::lastRequest
time lastRequest
UNIX timestamp (UTC) of last request sent.
Definition ServerMonitor.idl:92
servermon::ServerMonitor::Server
Server Entry.
Definition ServerMonitor.idl:165
servermon::ServerMonitor::Server::settings
ServerSettings settings
Server settings.
Definition ServerMonitor.idl:166
servermon::ServerMonitor::Server::status
ServerStatus status
Server status.
Definition ServerMonitor.idl:167