Raritan / Server Technology Xerus™ PDU JSON-RPC API: CascadeManager.idl Source File

Raritan / Server Technology Xerus™ PDU JSON-RPC API

CascadeManager.idl
1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /*
3 * Copyright 2018 Raritan Inc. All rights reserved.
4 */
5
6 #include <UserEvent.idl>
7
8 /** Raritan JSON-RPC */
9 module cascading {
10
11 /** JSON-RPC Cascade Manager */
12 interface CascadeManager {
13
14 constant int NO_ERROR = 0; ///< Operation successful, no error
15 constant int ERR_INVALID_PARAM = 1; ///< A parameter was invalid
16 constant int ERR_UNSUPPORTED_ON_PRIMARY_UNIT = 2; ///< Operation not allowed for a primary unit
17 constant int ERR_UNSUPPORTED_ON_LINK_UNIT = 3; ///< Operation not allowed for a link unit
18 constant int ERR_LINK_ID_IN_USE = 4; ///< The specified link ID is already used
19 constant int ERR_HOST_IN_USE = 5; ///< The specified host is already in use
20 constant int ERR_LINK_UNIT_UNREACHABLE = 6; ///< Could not connect to the link device
21 constant int ERR_LINK_UNIT_ACCESS_DENIED = 7; ///< Login to link device failed
22 constant int ERR_LINK_UNIT_REFUSED = 8; ///< Remote device refused to become a link unit
23 constant int ERR_UNIT_BUSY = 9; ///< The unit could not respond because it was busy
24 constant int ERR_NOT_SUPPORTED = 10; ///< Operation not supported on this device
25 constant int ERR_PASSWORD_CHANGE_REQUIRED = 11; ///< The unit requires a password change
26 constant int ERR_PASSWORD_POLICY = 12; ///< The given password did not meet the requirements
27 constant int ERR_LINK_UNIT_COMM_FAILED = 13; ///< Communication with the link unit failed
28 constant int ERR_LINK_UNIT_NOT_SUPPORTED = 14; ///< Link unit does not support cascading
29 constant int ERR_FIRMWARE_VERSION_MISMATCH = 15; ///< The firmware versions between primary and link unit do not match
30
31 /** Settings for primary unit */
32 structure PrimaryUnitSettings {
33 string caCertChain; ///< CA certificate chain that signs the link unit TLS certs
34 boolean allowOffTimeRangeCerts; ///< allow expired and not yet valid TLS certs
35 };
36
37 /** JSON-RPC Cascade Role */
38 enumeration Role {
39 STANDALONE, ///< Standalone unit, not in cascade
40 PRIMARY_UNIT, ///< Primary unit controlling other devices
41 LINK_UNIT ///< Link unit under primary unit control
42 };
43
44 enumeration LinkUnitType {
45 NETWORK, ///< High-level linking via JSON-RPC API
46 SECURE_SERIAL ///< Linking via encrypted serial bus (ScalePoint)
47 };
48
49 /** Link Unit Communication Status */
50 [unknown_fallback("UNKNOWN")]
51 enumeration LinkUnitStatus {
52 UNKNOWN, ///< The status of the link unit is unknown
53 OK, ///< The link unit operates normally
54 UNREACHABLE, ///< The link unit is unreachable
55 ACCESS_DENIED, ///< The link unit denies access
56 FIRMWARE_UPDATE, ///< This link unit is performing a firmware update
57 FIRMWARE_MISMATCH, ///< This link unit's firmware version does not match that of the primary unit
58 PENDING ///< The link unit becomes active after the next reboot
59 };
60
61 /** Link Unit Status */
62 structure LinkUnit {
63 LinkUnitType type; ///< Link unit type
64 string host; ///< Link unit host name, IP address or bus address
65 LinkUnitStatus status; ///< Communication status
66 string fwVersion; ///< Firmware version of the link unit
67 };
68
69 /** Full Cascading Status */
70 structure Status {
71 Role role; ///< This unit's role in the JSON-RPC cascade
72 string primaryUnit; ///< The primary unit IP address (if role is link unit)
73 map<int, LinkUnit> linkUnits; ///< The list of link units (if role is primary unit)
74 };
75
76 /** Status of the Link Port */
77 structure LinkPortStatus {
78 boolean isSupported; ///< true, if Link Port is supported on this device
79 boolean isLinkDetected; ///< true, if a link on the Link Port was detected
80 boolean isLinkingConfirmationNeeded; ///< true, if confirmation for linking via Link Port is needed
81 };
82
83 /** Event: This unit's role in the cascade has changed */
84 valueobject RoleChangedEvent extends idl.Event {
85 Role oldRole; ///< Previous role before the change
86 Role newRole; ///< New role after the change
87 string primaryUnit; ///< Primary unit IP address (if new role is link unit)
88 };
89
90 /** Event: A new link unit has been added */
91 valueobject LinkUnitAddedEvent extends event.UserEvent {
92 int linkId; ///< Link ID
93 LinkUnitType type; ///< Link unit type
94 string host; ///< Host name, IP address or bus address
95 };
96
97 /** Event: A link unit has been released */
98 valueobject LinkUnitReleasedEvent extends event.UserEvent {
99 int linkId; ///< Link ID
100 LinkUnitType type; ///< Link unit type
101 string host; ///< Host name, IP address or bus address
102 };
103
104 /** Event: A link unit's communication status has changed */
105 valueobject LinkUnitStatusChangedEvent extends idl.Event {
106 int linkId; ///< Link ID
107 LinkUnitType type; ///< Link unit type
108 string host; ///< Host name, IP address or bus address
109 LinkUnitStatus oldStatus; ///< Previous communication status
110 LinkUnitStatus newStatus; ///< New communication status
111 };
112
113 /** Link Port Status changed */
114 valueobject LinkPortStatusChangedEvent extends idl.Event {
115 LinkPortStatus oldStatus; ///< Old Link Port status
116 LinkPortStatus newStatus; ///< New Link Port status
117 };
118
119 /**
120 * Retrieve settings for the primary unit.
121 *
122 * @return Primary unit settings
123 */
124 PrimaryUnitSettings getPrimaryUnitSettings();
125
126 /**
127 * Set settings for the primary unit.
128 *
129 * @param primaryUnitSettings Primary unit settings
130 *
131 * @return NO_ERROR The operation was successful
132 * @return ERR_INVALID_PARAM At least one of the parameters had an invalid value
133 */
134 int setPrimaryUnitSettings(in PrimaryUnitSettings primaryUnitSettings);
135
136 /**
137 * Retrieve the full cascading status for this unit.
138 *
139 * @return Full cascading status
140 */
141 Status getStatus();
142
143 /**
144 * Retrieve the current Link Port status
145 *
146 * @return Current Link Port status
147 */
148 LinkPortStatus getLinkPortStatus();
149
150 /**
151 * Put a new link unit under this primary unit's control.
152 *
153 * The login credentials must have administrator privileges on the link
154 * unit. They are only used to establish a trust relationship between
155 * primary and link unit and not stored.
156 *
157 * This method can also be used to re-authenticate a link unit that
158 * denies access. In that case the linkId and host parameter must
159 * exactly match the existing values.
160 *
161 * @param linkId The ID for the new link unit
162 * @param host The link unit's host name or IP address
163 * @param login The administrator login for the link unit
164 * @param password The administrator password for the link unit
165 * @param newPassword The new administrator password for the unit.
166 * This is needed for adding a link unit that still has default
167 * settings and requires a password change. Otherwise it can be
168 * left empty.
169 *
170 * @return NO_ERROR The operation was successful
171 * @return ERR_INVALID_PARAM One of the parameters had an invalid value
172 * @return ERR_UNSUPPORTED_ON_LINK_UNIT This unit is currently a link unit and can't have link units of its own
173 * @return ERR_LINK_ID_IN_USE The specified link ID is already in use
174 * @return ERR_HOST_IN_USE The specified host is already in use
175 * @return ERR_LINK_UNIT_UNREACHABLE Connection to the link unit failed
176 * @return ERR_LINK_UNIT_ACCESS_DENIED The credentials for the link unit were invalid
177 * @return ERR_LINK_UNIT_REFUSED The remote unit refused to become our link unit because it's a primary unit itself
178 * @return ERR_UNIT_BUSY This unit is currently busy with handling another request
179 * @return ERR_NOT_SUPPORTED This device does not support PDU linking
180 * @return ERR_PASSWORD_CHANGE_REQUIRED The specified link unit requires a password change
181 * @return ERR_PASSWORD_POLICY The new password did not meet the requirements
182 * @return ERR_LINK_UNIT_COMM_FAILED Communication with the link unit failed
183 * @return ERR_LINK_UNIT_NOT_SUPPORTED Link unit does not support cascading
184 * @return ERR_FIRMWARE_VERSION_MISMATCH The firmware version of the link unit does not match that of the primary unit
185 */
186 int addLinkUnit(in int linkId, in string host, in string login, in string password, in string newPassword);
187
188 /**
189 * Release a link unit from this primary unit's control.
190 *
191 * @param linkId The ID of the link unit
192 *
193 * @return NO_ERROR The operation was successful
194 * @return ERR_INVALID_PARAM The specified link ID is invalid
195 */
196 int releaseLinkUnit(in int linkId);
197
198 /**
199 * Request to make this unit a link unit and put it under the remote
200 * primary unit's control.
201 *
202 * This method is usually called by the primary unit when adding a new
203 * link unit. The link will only be established once finalizeLink() is
204 * successfully called.
205 *
206 * @param token Authorization token for future requests
207 *
208 * @return NO_ERROR The operation was successful
209 * @return ERR_UNSUPPORTED_ON_PRIMARY_UNIT This unit is a primary unit and can't become a link unit
210 * @return ERR_NOT_SUPPORTED This device does not support PDU linking
211 */
212 int requestLink(in string token);
213
214 /**
215 * Finalize the link with this link unit.
216 *
217 * @param token same authorization token as used for requestLink()
218 *
219 * This method should only be called by the primary unit in order to
220 * acknowledge the establishment of the link to the link unit and
221 * finalize the link build-up. The linking will only take effect once
222 * the link unit received this acknowledgement.
223 *
224 * If this method fails, you will get the ACCESS_DENIED status for this
225 * link unit and you will have to re-authenticate it.
226 */
227 void finalizeLink(in string token);
228
229 /**
230 * Release this link unit from the remote primary unit's control.
231 *
232 * This method is usually called by the primary unit when releasing a
233 * link unit. This unit will become a standalone unit.
234 */
235 void unlink();
236
237 /**
238 * Check which cascading roles this unit supports.
239 *
240 * @return vector with Roles that are supported by this unit
241 */
242 vector<Role> getSupportedRoles();
243
244 /**
245 * Check which type of link units this unit supports.
246 *
247 * @return vector with supported link unit types
248 */
249 vector<LinkUnitType> getSupportedLinkUnitTypes();
250
251 /**
252 * Can be called on a network cascade primary unit to add expansion
253 * units of the network cascade as link units.
254 *
255 * @param linkId The ID for the new link unit
256 * @param nodeIndex The expansion unit's index in the network cascade (1 - 15)
257 * @param login The administrator login for the link unit
258 * @param password The administrator password for the link unit
259 * @param positionDependent If true, host names that depend on the nodex index will be used.
260 * If false, unique link-local IPv6 addresses will be used for linking.
261 *
262 * @return see \ref addLinkUnit
263 *
264 */
265 int addCascadeLinkUnit(in int linkId, in int nodeIndex, in string login, in string password, in boolean positionDependent);
266
267 /**
268 * Add a neighbor that was discovered on the link port as link unit. If
269 * a new password needs to be set, it will be generated.
270 *
271 * @return NO_ERROR The operation was successful
272 * @return ERR_INVALID_PARAM No neighbor currently discovered or no link id left
273 * @return ERR_UNSUPPORTED_ON_LINK_UNIT This unit is currently a link unit and can't have link units of its own
274 * @return ERR_HOST_IN_USE The link port neighbor was already added
275 * @return ERR_LINK_UNIT_UNREACHABLE Connection to the link unit failed
276 * @return ERR_LINK_UNIT_ACCESS_DENIED The credentials for the link unit were invalid
277 * @return ERR_LINK_UNIT_REFUSED The remote unit refused to become our link unit because it's a primary unit itself
278 * @return ERR_UNIT_BUSY This unit is currently busy with handling another request
279 * @return ERR_NOT_SUPPORTED This device does not support PDU linking via link port
280 * @return ERR_LINK_UNIT_COMM_FAILED Communication with the link unit failed
281 * @return ERR_LINK_UNIT_NOT_SUPPORTED Link unit does not support cascading
282 * @return ERR_FIRMWARE_VERSION_MISMATCH The firmware version of the link unit does not match that of the primary unit
283 */
284 int addLinkPortLinkUnit();
285
286 /**
287 * Add a serial link unit (ScalePoint Base).
288 *
289 * As a special case, link ID 1 is used to pair the primary unit on the
290 * "internal" RS485 bus. It will not be added to the list of link units.
291 *
292 * @param linkId The ID for the new link unit
293 * @param installKey The install key from the Base unit's label
294 *
295 * @return NO_ERROR The operation was successful
296 * @return ERR_INVALID_PARAM One of the parameters had an invalid value
297 * @return ERR_UNSUPPORTED_ON_LINK_UNIT This unit is currently a link unit and can't have link units of its own
298 * @return ERR_LINK_ID_IN_USE The specified link ID is already in use
299 * @return ERR_LINK_UNIT_UNREACHABLE Connection to the link unit failed
300 * @return ERR_UNIT_BUSY This unit is currently busy with handling another request
301 * @return ERR_NOT_SUPPORTED This device does not support PDU linking
302 * @return ERR_LINK_UNIT_COMM_FAILED Communication with the link unit failed
303 */
304 int addSecureSerialLinkUnit(in int linkId, in string installKey);
305
306 };
307
308 }
cascading::CascadeManager
JSON-RPC Cascade Manager.
Definition: CascadeManager.idl:12
cascading::CascadeManager::setPrimaryUnitSettings
int setPrimaryUnitSettings(in PrimaryUnitSettings primaryUnitSettings)
Set settings for the primary unit.
cascading::CascadeManager::getStatus
Status getStatus()
Retrieve the full cascading status for this unit.
cascading::CascadeManager::addLinkUnit
int addLinkUnit(in int linkId, in string host, in string login, in string password, in string newPassword)
Put a new link unit under this primary unit's control.
cascading::CascadeManager::getPrimaryUnitSettings
PrimaryUnitSettings getPrimaryUnitSettings()
Retrieve settings for the primary unit.
cascading::CascadeManager::addLinkPortLinkUnit
int addLinkPortLinkUnit()
Add a neighbor that was discovered on the link port as link unit.
cascading::CascadeManager::getSupportedRoles
vector< Role > getSupportedRoles()
Check which cascading roles this unit supports.
cascading::CascadeManager::requestLink
int requestLink(in string token)
Request to make this unit a link unit and put it under the remote primary unit's control.
cascading::CascadeManager::getLinkPortStatus
LinkPortStatus getLinkPortStatus()
Retrieve the current Link Port status.
cascading::CascadeManager::Role
Role
JSON-RPC Cascade Role.
Definition: CascadeManager.idl:38
cascading::CascadeManager::STANDALONE
@ STANDALONE
Standalone unit, not in cascade.
Definition: CascadeManager.idl:39
cascading::CascadeManager::PRIMARY_UNIT
@ PRIMARY_UNIT
Primary unit controlling other devices.
Definition: CascadeManager.idl:40
cascading::CascadeManager::finalizeLink
void finalizeLink(in string token)
Finalize the link with this link unit.
cascading::CascadeManager::getSupportedLinkUnitTypes
vector< LinkUnitType > getSupportedLinkUnitTypes()
Check which type of link units this unit supports.
cascading::CascadeManager::unlink
void unlink()
Release this link unit from the remote primary unit's control.
cascading::CascadeManager::LinkUnitStatus
LinkUnitStatus
Link Unit Communication Status.
Definition: CascadeManager.idl:51
cascading::CascadeManager::FIRMWARE_UPDATE
@ FIRMWARE_UPDATE
This link unit is performing a firmware update.
Definition: CascadeManager.idl:56
cascading::CascadeManager::FIRMWARE_MISMATCH
@ FIRMWARE_MISMATCH
This link unit's firmware version does not match that of the primary unit.
Definition: CascadeManager.idl:57
cascading::CascadeManager::ACCESS_DENIED
@ ACCESS_DENIED
The link unit denies access.
Definition: CascadeManager.idl:55
cascading::CascadeManager::OK
@ OK
The link unit operates normally.
Definition: CascadeManager.idl:53
cascading::CascadeManager::UNKNOWN
@ UNKNOWN
The status of the link unit is unknown.
Definition: CascadeManager.idl:52
cascading::CascadeManager::UNREACHABLE
@ UNREACHABLE
The link unit is unreachable.
Definition: CascadeManager.idl:54
cascading::CascadeManager::addCascadeLinkUnit
int addCascadeLinkUnit(in int linkId, in int nodeIndex, in string login, in string password, in boolean positionDependent)
Can be called on a network cascade primary unit to add expansion units of the network cascade as link...
cascading::CascadeManager::LinkUnitType
LinkUnitType
Definition: CascadeManager.idl:44
cascading::CascadeManager::NETWORK
@ NETWORK
High-level linking via JSON-RPC API.
Definition: CascadeManager.idl:45
cascading::CascadeManager::releaseLinkUnit
int releaseLinkUnit(in int linkId)
Release a link unit from this primary unit's control.
cascading::CascadeManager::addSecureSerialLinkUnit
int addSecureSerialLinkUnit(in int linkId, in string installKey)
Add a serial link unit (ScalePoint Base).
cascading
Raritan JSON-RPC.
Definition: CascadeManager.idl:9
idl
Basic IDL definitions.
Definition: Event.idl:10
cascading::CascadeManager::LinkPortStatusChangedEvent
Link Port Status changed.
Definition: CascadeManager.idl:114
cascading::CascadeManager::LinkPortStatusChangedEvent::oldStatus
LinkPortStatus oldStatus
Old Link Port status.
Definition: CascadeManager.idl:115
cascading::CascadeManager::LinkPortStatusChangedEvent::newStatus
LinkPortStatus newStatus
New Link Port status.
Definition: CascadeManager.idl:116
cascading::CascadeManager::LinkPortStatus
Status of the Link Port.
Definition: CascadeManager.idl:77
cascading::CascadeManager::LinkPortStatus::isLinkingConfirmationNeeded
boolean isLinkingConfirmationNeeded
true, if confirmation for linking via Link Port is needed
Definition: CascadeManager.idl:80
cascading::CascadeManager::LinkPortStatus::isSupported
boolean isSupported
true, if Link Port is supported on this device
Definition: CascadeManager.idl:78
cascading::CascadeManager::LinkPortStatus::isLinkDetected
boolean isLinkDetected
true, if a link on the Link Port was detected
Definition: CascadeManager.idl:79
cascading::CascadeManager::LinkUnitAddedEvent
Event: A new link unit has been added.
Definition: CascadeManager.idl:91
cascading::CascadeManager::LinkUnitAddedEvent::type
LinkUnitType type
Link unit type.
Definition: CascadeManager.idl:93
cascading::CascadeManager::LinkUnitAddedEvent::linkId
int linkId
Link ID.
Definition: CascadeManager.idl:92
cascading::CascadeManager::LinkUnitAddedEvent::host
string host
Host name, IP address or bus address.
Definition: CascadeManager.idl:94
cascading::CascadeManager::LinkUnitReleasedEvent
Event: A link unit has been released.
Definition: CascadeManager.idl:98
cascading::CascadeManager::LinkUnitReleasedEvent::linkId
int linkId
Link ID.
Definition: CascadeManager.idl:99
cascading::CascadeManager::LinkUnitReleasedEvent::host
string host
Host name, IP address or bus address.
Definition: CascadeManager.idl:101
cascading::CascadeManager::LinkUnitReleasedEvent::type
LinkUnitType type
Link unit type.
Definition: CascadeManager.idl:100
cascading::CascadeManager::LinkUnitStatusChangedEvent
Event: A link unit's communication status has changed.
Definition: CascadeManager.idl:105
cascading::CascadeManager::LinkUnitStatusChangedEvent::oldStatus
LinkUnitStatus oldStatus
Previous communication status.
Definition: CascadeManager.idl:109
cascading::CascadeManager::LinkUnitStatusChangedEvent::host
string host
Host name, IP address or bus address.
Definition: CascadeManager.idl:108
cascading::CascadeManager::LinkUnitStatusChangedEvent::newStatus
LinkUnitStatus newStatus
New communication status.
Definition: CascadeManager.idl:110
cascading::CascadeManager::LinkUnitStatusChangedEvent::linkId
int linkId
Link ID.
Definition: CascadeManager.idl:106
cascading::CascadeManager::LinkUnitStatusChangedEvent::type
LinkUnitType type
Link unit type.
Definition: CascadeManager.idl:107
cascading::CascadeManager::LinkUnit
Link Unit Status.
Definition: CascadeManager.idl:62
cascading::CascadeManager::LinkUnit::type
LinkUnitType type
Link unit type.
Definition: CascadeManager.idl:63
cascading::CascadeManager::LinkUnit::status
LinkUnitStatus status
Communication status.
Definition: CascadeManager.idl:65
cascading::CascadeManager::LinkUnit::fwVersion
string fwVersion
Firmware version of the link unit.
Definition: CascadeManager.idl:66
cascading::CascadeManager::LinkUnit::host
string host
Link unit host name, IP address or bus address.
Definition: CascadeManager.idl:64
cascading::CascadeManager::PrimaryUnitSettings
Settings for primary unit.
Definition: CascadeManager.idl:32
cascading::CascadeManager::PrimaryUnitSettings::caCertChain
string caCertChain
CA certificate chain that signs the link unit TLS certs.
Definition: CascadeManager.idl:33
cascading::CascadeManager::PrimaryUnitSettings::allowOffTimeRangeCerts
boolean allowOffTimeRangeCerts
allow expired and not yet valid TLS certs
Definition: CascadeManager.idl:34
cascading::CascadeManager::RoleChangedEvent
Event: This unit's role in the cascade has changed.
Definition: CascadeManager.idl:84
cascading::CascadeManager::RoleChangedEvent::primaryUnit
string primaryUnit
Primary unit IP address (if new role is link unit)
Definition: CascadeManager.idl:87
cascading::CascadeManager::RoleChangedEvent::oldRole
Role oldRole
Previous role before the change.
Definition: CascadeManager.idl:85
cascading::CascadeManager::RoleChangedEvent::newRole
Role newRole
New role after the change.
Definition: CascadeManager.idl:86
cascading::CascadeManager::Status
Full Cascading Status.
Definition: CascadeManager.idl:70
cascading::CascadeManager::Status::primaryUnit
string primaryUnit
The primary unit IP address (if role is link unit)
Definition: CascadeManager.idl:72
cascading::CascadeManager::Status::linkUnits
map< int, LinkUnit > linkUnits
The list of link units (if role is primary unit)
Definition: CascadeManager.idl:73
cascading::CascadeManager::Status::role
Role role
This unit's role in the JSON-RPC cascade.
Definition: CascadeManager.idl:71
idl::Event
Common base for all events.
Definition: Event.idl:13