]>
Commit | Line | Data |
---|---|---|
ec2ac5f2 | 1 | // |
4049b01b | 2 | // Copyright 2019 FRRouting |
ec2ac5f2 | 3 | // |
4049b01b RW |
4 | // Redistribution and use in source and binary forms, with or without |
5 | // modification, are permitted provided that the following conditions are met: | |
ec2ac5f2 | 6 | // |
4049b01b RW |
7 | // 1. Redistributions of source code must retain the above copyright notice, |
8 | // this list of conditions and the following disclaimer. | |
ec2ac5f2 | 9 | // |
4049b01b RW |
10 | // 2. Redistributions in binary form must reproduce the above copyright |
11 | // notice, this list of conditions and the following disclaimer in the | |
12 | // documentation and/or other materials provided with the distribution. | |
13 | // | |
14 | // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" | |
15 | // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
16 | // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
17 | // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS | |
18 | // BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, | |
19 | // OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | |
20 | // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
21 | // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |
22 | // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
23 | // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF | |
24 | // THE POSSIBILITY OF SUCH DAMAGE. | |
ec2ac5f2 RW |
25 | // |
26 | ||
27 | syntax = "proto3"; | |
28 | ||
29 | package frr; | |
30 | ||
31 | // Service specification for the FRR northbound interface. | |
32 | service Northbound { | |
33 | // Retrieve the capabilities supported by the target. | |
34 | rpc GetCapabilities(GetCapabilitiesRequest) returns (GetCapabilitiesResponse) {} | |
35 | ||
36 | // Retrieve configuration data, state data or both from the target. | |
37 | rpc Get(GetRequest) returns (stream GetResponse) {} | |
38 | ||
39 | // Create a new candidate configuration and return a reference to it. The | |
40 | // created candidate is a copy of the running configuration. | |
41 | rpc CreateCandidate(CreateCandidateRequest) returns (CreateCandidateResponse) {} | |
42 | ||
43 | // Delete a candidate configuration. | |
44 | rpc DeleteCandidate(DeleteCandidateRequest) returns (DeleteCandidateResponse) {} | |
45 | ||
46 | // Update a candidate configuration by rebasing the changes on top of the | |
47 | // latest running configuration. Resolve conflicts automatically by giving | |
48 | // preference to the changes done in the candidate configuration. | |
49 | rpc UpdateCandidate(UpdateCandidateRequest) returns (UpdateCandidateResponse) {} | |
50 | ||
51 | // Edit a candidate configuration. All changes are discarded if any error | |
52 | // happens. | |
53 | rpc EditCandidate(EditCandidateRequest) returns (EditCandidateResponse) {} | |
54 | ||
55 | // Load configuration data into a candidate configuration. Both merge and | |
56 | // replace semantics are supported. | |
57 | rpc LoadToCandidate(LoadToCandidateRequest) returns (LoadToCandidateResponse) {} | |
58 | ||
59 | // Create a new configuration transaction using a two-phase commit protocol. | |
60 | rpc Commit(CommitRequest) returns (CommitResponse) {} | |
61 | ||
62 | // List the metadata of all configuration transactions recorded in the | |
63 | // transactions database. | |
64 | rpc ListTransactions(ListTransactionsRequest) returns (stream ListTransactionsResponse) {} | |
65 | ||
66 | // Fetch a configuration (identified by its transaction ID) from the | |
67 | // transactions database. | |
68 | rpc GetTransaction(GetTransactionRequest) returns (GetTransactionResponse) {} | |
69 | ||
70 | // Lock the running configuration, preventing other users from changing it. | |
71 | rpc LockConfig(LockConfigRequest) returns (LockConfigResponse) {} | |
72 | ||
73 | // Unlock the running configuration. | |
74 | rpc UnlockConfig(UnlockConfigRequest) returns (UnlockConfigResponse) {} | |
75 | ||
76 | // Execute a YANG RPC. | |
77 | rpc Execute(ExecuteRequest) returns (ExecuteResponse) {} | |
78 | } | |
79 | ||
80 | // ----------------------- Parameters and return types ------------------------- | |
81 | ||
82 | // | |
83 | // RPC: GetCapabilities() | |
84 | // | |
85 | message GetCapabilitiesRequest { | |
86 | // Empty. | |
87 | } | |
88 | ||
89 | message GetCapabilitiesResponse { | |
90 | // Return values: | |
91 | // - grpc::StatusCode::OK: Success. | |
92 | ||
93 | // FRR version. | |
94 | string frr_version = 1; | |
95 | ||
96 | // Indicates whether FRR was compiled with support for configuration | |
97 | // rollbacks or not (--enable-config-rollbacks). | |
98 | bool rollback_support = 2; | |
99 | ||
100 | // Supported schema modules. | |
101 | repeated ModuleData supported_modules = 3; | |
102 | ||
103 | // Supported encodings. | |
104 | repeated Encoding supported_encodings = 4; | |
105 | } | |
106 | ||
107 | // | |
108 | // RPC: Get() | |
109 | // | |
110 | message GetRequest { | |
111 | // Type of elements within the data tree. | |
112 | enum DataType { | |
113 | // All data elements. | |
114 | ALL = 0; | |
115 | ||
116 | // Config elements. | |
117 | CONFIG = 1; | |
118 | ||
119 | // State elements. | |
120 | STATE = 2; | |
121 | } | |
122 | ||
123 | // The type of data being requested. | |
124 | DataType type = 1; | |
125 | ||
126 | // Encoding to be used. | |
127 | Encoding encoding = 2; | |
128 | ||
129 | // Include implicit default nodes. | |
130 | bool with_defaults = 3; | |
131 | ||
132 | // Paths requested by the client. | |
133 | repeated string path = 4; | |
134 | } | |
135 | ||
136 | message GetResponse { | |
137 | // Return values: | |
138 | // - grpc::StatusCode::OK: Success. | |
139 | // - grpc::StatusCode::INVALID_ARGUMENT: Invalid YANG data path. | |
140 | ||
141 | // Timestamp in nanoseconds since Epoch. | |
142 | int64 timestamp = 1; | |
143 | ||
144 | // The requested data. | |
145 | DataTree data = 2; | |
146 | } | |
147 | ||
148 | // | |
149 | // RPC: CreateCandidate() | |
150 | // | |
151 | message CreateCandidateRequest { | |
152 | // Empty. | |
153 | } | |
154 | ||
155 | message CreateCandidateResponse { | |
156 | // Return values: | |
157 | // - grpc::StatusCode::OK: Success. | |
158 | // - grpc::StatusCode::RESOURCE_EXHAUSTED: can't create candidate | |
159 | // configuration. | |
160 | ||
161 | // Handle to the new created candidate configuration. | |
162 | uint32 candidate_id = 1; | |
163 | } | |
164 | ||
165 | // | |
166 | // RPC: DeleteCandidate() | |
167 | // | |
168 | message DeleteCandidateRequest { | |
169 | // Candidate configuration to delete. | |
170 | uint32 candidate_id = 1; | |
171 | } | |
172 | ||
173 | message DeleteCandidateResponse { | |
174 | // Return values: | |
175 | // - grpc::StatusCode::OK: Success. | |
176 | // - grpc::StatusCode::NOT_FOUND: Candidate wasn't found. | |
177 | } | |
178 | ||
179 | // | |
180 | // RPC: UpdateCandidate() | |
181 | // | |
182 | message UpdateCandidateRequest { | |
183 | // Candidate configuration to update. | |
184 | uint32 candidate_id = 1; | |
185 | } | |
186 | ||
187 | message UpdateCandidateResponse { | |
188 | // Return values: | |
189 | // - grpc::StatusCode::OK: Success. | |
190 | // - grpc::StatusCode::NOT_FOUND: Candidate wasn't found. | |
191 | } | |
192 | ||
193 | // | |
194 | // RPC: EditCandidate() | |
195 | // | |
196 | message EditCandidateRequest { | |
197 | // Candidate configuration that is going to be edited. | |
198 | uint32 candidate_id = 1; | |
199 | ||
200 | // Data elements to be created or updated. | |
201 | repeated PathValue update = 2; | |
202 | ||
203 | // Paths to be deleted from the data tree. | |
204 | repeated PathValue delete = 3; | |
205 | } | |
206 | ||
207 | message EditCandidateResponse { | |
208 | // Return values: | |
209 | // - grpc::StatusCode::OK: Success. | |
210 | // - grpc::StatusCode::NOT_FOUND: Candidate wasn't found. | |
211 | // - grpc::StatusCode::INVALID_ARGUMENT: An error occurred while editing the | |
212 | // candidate configuration. | |
213 | } | |
214 | ||
215 | // | |
216 | // RPC: LoadToCandidate() | |
217 | // | |
218 | message LoadToCandidateRequest { | |
219 | enum LoadType { | |
220 | // Merge the data tree into the candidate configuration. | |
221 | MERGE = 0; | |
222 | ||
223 | // Replace the candidate configuration by the provided data tree. | |
224 | REPLACE = 1; | |
225 | } | |
226 | ||
227 | // Candidate configuration that is going to be edited. | |
228 | uint32 candidate_id = 1; | |
229 | ||
230 | // Load operation to apply. | |
231 | LoadType type = 2; | |
232 | ||
233 | // Configuration data. | |
234 | DataTree config = 3; | |
235 | } | |
236 | ||
237 | message LoadToCandidateResponse { | |
238 | // Return values: | |
239 | // - grpc::StatusCode::OK: Success. | |
240 | // - grpc::StatusCode::INVALID_ARGUMENT: An error occurred while performing | |
241 | // the load operation. | |
242 | } | |
243 | ||
244 | // | |
245 | // RPC: Commit() | |
246 | // | |
247 | message CommitRequest { | |
248 | enum Phase { | |
249 | // Validate if the configuration changes are valid (phase 0). | |
250 | VALIDATE = 0; | |
251 | ||
252 | // Prepare resources to apply the configuration changes (phase 1). | |
253 | PREPARE = 1; | |
254 | ||
255 | // Release previously allocated resources (phase 2). | |
256 | ABORT = 2; | |
257 | ||
258 | // Apply the configuration changes (phase 2). | |
259 | APPLY = 3; | |
260 | ||
261 | // All of the above (VALIDATE + PREPARE + ABORT/APPLY). | |
262 | // | |
263 | // This option can't be used to implement network-wide transactions, | |
264 | // since they require the manager entity to take into account the results | |
265 | // of the preparation phase of multiple managed devices. | |
266 | ALL = 4; | |
267 | } | |
268 | ||
269 | // Candidate configuration that is going to be committed. | |
270 | uint32 candidate_id = 1; | |
271 | ||
272 | // Transaction phase. | |
273 | Phase phase = 2; | |
274 | ||
275 | // Assign a comment to this commit. | |
276 | string comment = 3; | |
277 | } | |
278 | ||
279 | message CommitResponse { | |
280 | // Return values: | |
281 | // - grpc::StatusCode::OK: Success. | |
282 | // - grpc::StatusCode::FAILED_PRECONDITION: misuse of the two-phase commit | |
283 | // protocol. | |
284 | // - grpc::StatusCode::INVALID_ARGUMENT: Validation error. | |
285 | // - grpc::StatusCode::RESOURCE_EXHAUSTED: Failure to allocate resource. | |
286 | ||
287 | // ID of the created configuration transaction (when the phase is APPLY | |
288 | // or ALL). | |
289 | uint32 transaction_id = 1; | |
0fe5b904 RW |
290 | |
291 | // Human-readable error or warning message(s). | |
292 | string error_message = 2; | |
ec2ac5f2 RW |
293 | } |
294 | ||
295 | // | |
296 | // RPC: ListTransactions() | |
297 | // | |
298 | message ListTransactionsRequest { | |
299 | // Empty. | |
300 | } | |
301 | ||
302 | message ListTransactionsResponse { | |
303 | // Return values: | |
304 | // - grpc::StatusCode::OK: Success. | |
305 | ||
306 | // Transaction ID. | |
307 | uint32 id = 1; | |
308 | ||
309 | // Client that committed the transaction. | |
310 | string client = 2; | |
311 | ||
312 | // Date and time the transaction was committed. | |
313 | string date = 3; | |
314 | ||
315 | // Comment assigned to the transaction. | |
316 | string comment = 4; | |
317 | } | |
318 | ||
319 | // | |
320 | // RPC: GetTransaction() | |
321 | // | |
322 | message GetTransactionRequest { | |
323 | // Transaction to retrieve. | |
324 | uint32 transaction_id = 1; | |
325 | ||
326 | // Encoding to be used. | |
327 | Encoding encoding = 2; | |
328 | ||
329 | // Include implicit default nodes. | |
330 | bool with_defaults = 3; | |
331 | } | |
332 | ||
333 | message GetTransactionResponse { | |
334 | // Return values: | |
335 | // - grpc::StatusCode::OK: Success. | |
336 | // - grpc::StatusCode::NOT_FOUND: Transaction wasn't found in the transactions | |
337 | // database. | |
338 | ||
339 | DataTree config = 1; | |
340 | } | |
341 | ||
342 | // | |
343 | // RPC: LockConfig() | |
344 | // | |
345 | message LockConfigRequest { | |
346 | // Empty. | |
347 | } | |
348 | ||
349 | message LockConfigResponse { | |
350 | // Return values: | |
351 | // - grpc::StatusCode::OK: Success. | |
352 | // - grpc::StatusCode::FAILED_PRECONDITION: Running configuration is | |
353 | // locked already. | |
354 | } | |
355 | ||
356 | // | |
357 | // RPC: UnlockConfig() | |
358 | // | |
359 | message UnlockConfigRequest { | |
360 | // Empty. | |
361 | } | |
362 | ||
363 | message UnlockConfigResponse { | |
364 | // Return values: | |
365 | // - grpc::StatusCode::OK: Success. | |
366 | // - grpc::StatusCode::FAILED_PRECONDITION: Running configuration isn't | |
367 | // locked. | |
368 | } | |
369 | ||
370 | // | |
371 | // RPC: Execute() | |
372 | // | |
373 | message ExecuteRequest { | |
374 | // Path of the YANG RPC or YANG Action. | |
375 | string path = 1; | |
376 | ||
377 | // Input parameters. | |
378 | repeated PathValue input = 2; | |
379 | } | |
380 | ||
381 | message ExecuteResponse { | |
382 | // Return values: | |
383 | // - grpc::StatusCode::OK: Success. | |
384 | ||
385 | // Output parameters. | |
386 | repeated PathValue output = 1; | |
387 | } | |
388 | ||
389 | // -------------------------------- Definitions -------------------------------- | |
390 | ||
391 | // YANG module. | |
392 | message ModuleData { | |
393 | // Name of the YANG module; | |
394 | string name = 1; | |
395 | ||
396 | // Organization publishing the module. | |
397 | string organization = 2; | |
398 | ||
399 | // Latest revision of the module; | |
400 | string revision = 3; | |
401 | } | |
402 | ||
403 | // Supported encodings for YANG instance data. | |
404 | enum Encoding { | |
405 | JSON = 0; | |
406 | XML = 1; | |
407 | } | |
408 | ||
409 | // Path-value pair representing a data element. | |
410 | message PathValue { | |
411 | // YANG data path. | |
412 | string path = 1; | |
413 | ||
414 | // Data value. | |
415 | string value = 2; | |
416 | } | |
417 | ||
418 | // YANG instance data. | |
419 | message DataTree { | |
420 | Encoding encoding = 1; | |
421 | string data = 2; | |
422 | } |