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