2 // Copyright 2019 FRRouting
4 // Redistribution and use in source and binary forms, with or without
5 // modification, are permitted provided that the following conditions are met:
7 // 1. Redistributions of source code must retain the above copyright notice,
8 // this list of conditions and the following disclaimer.
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.
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.
31 // Service specification for the FRR northbound interface.
33 // Retrieve the capabilities supported by the target.
34 rpc GetCapabilities(GetCapabilitiesRequest) returns (GetCapabilitiesResponse) {}
36 // Retrieve configuration data, state data or both from the target.
37 rpc Get(GetRequest) returns (stream GetResponse) {}
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) {}
43 // Delete a candidate configuration.
44 rpc DeleteCandidate(DeleteCandidateRequest) returns (DeleteCandidateResponse) {}
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) {}
51 // Edit a candidate configuration. All changes are discarded if any error
53 rpc EditCandidate(EditCandidateRequest) returns (EditCandidateResponse) {}
55 // Load configuration data into a candidate configuration. Both merge and
56 // replace semantics are supported.
57 rpc LoadToCandidate(LoadToCandidateRequest) returns (LoadToCandidateResponse) {}
59 // Create a new configuration transaction using a two-phase commit protocol.
60 rpc Commit(CommitRequest) returns (CommitResponse) {}
62 // List the metadata of all configuration transactions recorded in the
63 // transactions database.
64 rpc ListTransactions(ListTransactionsRequest) returns (stream ListTransactionsResponse) {}
66 // Fetch a configuration (identified by its transaction ID) from the
67 // transactions database.
68 rpc GetTransaction(GetTransactionRequest) returns (GetTransactionResponse) {}
70 // Lock the running configuration, preventing other users from changing it.
71 rpc LockConfig(LockConfigRequest) returns (LockConfigResponse) {}
73 // Unlock the running configuration.
74 rpc UnlockConfig(UnlockConfigRequest) returns (UnlockConfigResponse) {}
76 // Execute a YANG RPC.
77 rpc Execute(ExecuteRequest) returns (ExecuteResponse) {}
80 // ----------------------- Parameters and return types -------------------------
83 // RPC: GetCapabilities()
85 message GetCapabilitiesRequest {
89 message GetCapabilitiesResponse {
91 // - grpc::StatusCode::OK: Success.
94 string frr_version = 1;
96 // Indicates whether FRR was compiled with support for configuration
97 // rollbacks or not (--enable-config-rollbacks).
98 bool rollback_support = 2;
100 // Supported schema modules.
101 repeated ModuleData supported_modules = 3;
103 // Supported encodings.
104 repeated Encoding supported_encodings = 4;
111 // Type of elements within the data tree.
113 // All data elements.
123 // The type of data being requested.
126 // Encoding to be used.
127 Encoding encoding = 2;
129 // Include implicit default nodes.
130 bool with_defaults = 3;
132 // Paths requested by the client.
133 repeated string path = 4;
136 message GetResponse {
138 // - grpc::StatusCode::OK: Success.
139 // - grpc::StatusCode::INVALID_ARGUMENT: Invalid YANG data path.
141 // Timestamp in nanoseconds since Epoch.
144 // The requested data.
149 // RPC: CreateCandidate()
151 message CreateCandidateRequest {
155 message CreateCandidateResponse {
157 // - grpc::StatusCode::OK: Success.
158 // - grpc::StatusCode::RESOURCE_EXHAUSTED: can't create candidate
161 // Handle to the new created candidate configuration.
162 uint32 candidate_id = 1;
166 // RPC: DeleteCandidate()
168 message DeleteCandidateRequest {
169 // Candidate configuration to delete.
170 uint32 candidate_id = 1;
173 message DeleteCandidateResponse {
175 // - grpc::StatusCode::OK: Success.
176 // - grpc::StatusCode::NOT_FOUND: Candidate wasn't found.
180 // RPC: UpdateCandidate()
182 message UpdateCandidateRequest {
183 // Candidate configuration to update.
184 uint32 candidate_id = 1;
187 message UpdateCandidateResponse {
189 // - grpc::StatusCode::OK: Success.
190 // - grpc::StatusCode::NOT_FOUND: Candidate wasn't found.
194 // RPC: EditCandidate()
196 message EditCandidateRequest {
197 // Candidate configuration that is going to be edited.
198 uint32 candidate_id = 1;
200 // Data elements to be created or updated.
201 repeated PathValue update = 2;
203 // Paths to be deleted from the data tree.
204 repeated PathValue delete = 3;
207 message EditCandidateResponse {
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.
216 // RPC: LoadToCandidate()
218 message LoadToCandidateRequest {
220 // Merge the data tree into the candidate configuration.
223 // Replace the candidate configuration by the provided data tree.
227 // Candidate configuration that is going to be edited.
228 uint32 candidate_id = 1;
230 // Load operation to apply.
233 // Configuration data.
237 message LoadToCandidateResponse {
239 // - grpc::StatusCode::OK: Success.
240 // - grpc::StatusCode::INVALID_ARGUMENT: An error occurred while performing
241 // the load operation.
247 message CommitRequest {
249 // Validate if the configuration changes are valid (phase 0).
252 // Prepare resources to apply the configuration changes (phase 1).
255 // Release previously allocated resources (phase 2).
258 // Apply the configuration changes (phase 2).
261 // All of the above (VALIDATE + PREPARE + ABORT/APPLY).
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.
269 // Candidate configuration that is going to be committed.
270 uint32 candidate_id = 1;
272 // Transaction phase.
275 // Assign a comment to this commit.
279 message CommitResponse {
281 // - grpc::StatusCode::OK: Success.
282 // - grpc::StatusCode::FAILED_PRECONDITION: misuse of the two-phase commit
284 // - grpc::StatusCode::INVALID_ARGUMENT: Validation error.
285 // - grpc::StatusCode::RESOURCE_EXHAUSTED: Failure to allocate resource.
287 // ID of the created configuration transaction (when the phase is APPLY
289 uint32 transaction_id = 1;
291 // Human-readable error or warning message(s).
292 string error_message = 2;
296 // RPC: ListTransactions()
298 message ListTransactionsRequest {
302 message ListTransactionsResponse {
304 // - grpc::StatusCode::OK: Success.
309 // Client that committed the transaction.
312 // Date and time the transaction was committed.
315 // Comment assigned to the transaction.
320 // RPC: GetTransaction()
322 message GetTransactionRequest {
323 // Transaction to retrieve.
324 uint32 transaction_id = 1;
326 // Encoding to be used.
327 Encoding encoding = 2;
329 // Include implicit default nodes.
330 bool with_defaults = 3;
333 message GetTransactionResponse {
335 // - grpc::StatusCode::OK: Success.
336 // - grpc::StatusCode::NOT_FOUND: Transaction wasn't found in the transactions
345 message LockConfigRequest {
349 message LockConfigResponse {
351 // - grpc::StatusCode::OK: Success.
352 // - grpc::StatusCode::FAILED_PRECONDITION: Running configuration is
357 // RPC: UnlockConfig()
359 message UnlockConfigRequest {
363 message UnlockConfigResponse {
365 // - grpc::StatusCode::OK: Success.
366 // - grpc::StatusCode::FAILED_PRECONDITION: Running configuration isn't
373 message ExecuteRequest {
374 // Path of the YANG RPC or YANG Action.
378 repeated PathValue input = 2;
381 message ExecuteResponse {
383 // - grpc::StatusCode::OK: Success.
385 // Output parameters.
386 repeated PathValue output = 1;
389 // -------------------------------- Definitions --------------------------------
393 // Name of the YANG module;
396 // Organization publishing the module.
397 string organization = 2;
399 // Latest revision of the module;
403 // Supported encodings for YANG instance data.
409 // Path-value pair representing a data element.
418 // YANG instance data.
420 Encoding encoding = 1;