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  */
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 }
int timeout
Seconds the power check takes before it ends / times out.
Definition: ServerMonitor.idl:62
Server Monitor Interface.
Definition: ServerMonitor.idl:13
Server power target is on.
Definition: ServerMonitor.idl:30
No response from server.
Definition: ServerMonitor.idl:21
boolean on
True if server shall be switched on, false otherwise.
Definition: ServerMonitor.idl:116
int sshPort
SSH port of the server.
Definition: ServerMonitor.idl:66
ServerReachability reachable
Reachability state.
Definition: ServerMonitor.idl:91
ServerSettings newSettings
Settings after change.
Definition: ServerMonitor.idl:152
ServerPowerState
Server Power Control State.
Definition: ServerMonitor.idl:28
Switching the outlet or outlet group off failed.
Definition: ServerMonitor.idl:41
ServerPowerControlResult
Server Power Control Result.
Definition: ServerMonitor.idl:38
ServerStatus status
Server status.
Definition: ServerMonitor.idl:167
ServerSettings settings
Server settings.
Definition: ServerMonitor.idl:166
int resumeCount
Number of resumes before going back to WAITING state.
Definition: ServerMonitor.idl:81
int responses
Number of responses received.
Definition: ServerMonitor.idl:95
Object target
Target for power control, Outlet or OutletGroup.
Definition: ServerMonitor.idl:59
Power state currently not known.
Definition: ServerMonitor.idl:29
Error issuing the shutdown command to the server.
Definition: ServerMonitor.idl:40
ServerSettings settings
Settings of the added server.
Definition: ServerMonitor.idl:143
boolean enabled
Pinging enabled.
Definition: ServerMonitor.idl:75
ServerPowerControlResult result
Result of the power control operation.
Definition: ServerMonitor.idl:125
Server is up and running.
Definition: ServerMonitor.idl:20
int requests
Number of requests sent.
Definition: ServerMonitor.idl:94
ServerSettings oldSettings
Settings before change.
Definition: ServerMonitor.idl:151
ServerReachability
Server Reachability State.
Definition: ServerMonitor.idl:18
string host
Server hostname/IP address.
Definition: ServerMonitor.idl:105
int activationCount
Minimum number of successful pings to enable feature.
Definition: ServerMonitor.idl:78
boolean enabled
Power control for this server enabled.
Definition: ServerMonitor.idl:58
Basic IDL definitions.
Definition: Event.idl:10
int failures
Number of consecutive failed pings.
Definition: ServerMonitor.idl:96
ServerReachability reachable
Current Reachability state.
Definition: ServerMonitor.idl:135
ServerPowerCheckMethod powerCheck
Method to check server&#39;s power state.
Definition: ServerMonitor.idl:60
ServerPowerSettings powerSettings
Settings for controlling the power state of the server.
Definition: ServerMonitor.idl:82
Server Entry.
Definition: ServerMonitor.idl:165
Server is assumed to be off after a time interval.
Definition: ServerMonitor.idl:50
int pingInterval
Wait time after successful ping.
Definition: ServerMonitor.idl:76
string username
Login used to issue shutdown command to the server.
Definition: ServerMonitor.idl:64
ServerPowerState oldPowerState
Old power state.
Definition: ServerMonitor.idl:106
string host
Server hostname/IP address.
Definition: ServerMonitor.idl:74
Server Reachability Status.
Definition: ServerMonitor.idl:88
ServerPowerControlResult lastPowerControlResult
Last result of a power control operation.
Definition: ServerMonitor.idl:90
int failureCount
Number of unsuccessful pings to consider server down.
Definition: ServerMonitor.idl:79
int resumeDelay
Wait time before resuming pinging.
Definition: ServerMonitor.idl:80
Settings for controlling and checking power state of the server.
Definition: ServerMonitor.idl:57
string shutdownCmd
Shutdown command to send to the server.
Definition: ServerMonitor.idl:63
ServerPowerCheckMethod
Methods of checking power state.
Definition: ServerMonitor.idl:49
time lastRequest
Timestamp of last request sent.
Definition: ServerMonitor.idl:92
string password
Password for the login, write-only, not set if empty.
Definition: ServerMonitor.idl:65
Switching the outlet or outlet group on failed.
Definition: ServerMonitor.idl:42
ServerPowerState newPowerState
New power state.
Definition: ServerMonitor.idl:107
Server power target is off.
Definition: ServerMonitor.idl:31
Waiting for reliable connection.
Definition: ServerMonitor.idl:19
int retryInterval
Wait time after unsuccessful ping.
Definition: ServerMonitor.idl:77
time lastResponse
Timestamp of last response received.
Definition: ServerMonitor.idl:93
double powerThreshold
Active power below this threshold means server is off (in Watt)
Definition: ServerMonitor.idl:61
No error, operation may still be in progress.
Definition: ServerMonitor.idl:39
ServerPowerState powerState
Power control state.
Definition: ServerMonitor.idl:89
Server Reachability Settings.
Definition: ServerMonitor.idl:73
int resumes
Number of resumes.
Definition: ServerMonitor.idl:97
Server Monitor.
Definition: ServerMonitor.idl:10