1 // SPDX-License-Identifier: BSD-2-Clause
3 // Copyright 2019 FRRouting
5 // Redistribution and use in source and binary forms, with or without
6 // modification, are permitted provided that the following conditions are met:
8 // 1. Redistributions of source code must retain the above copyright notice,
9 // this list of conditions and the following disclaimer.
11 // 2. Redistributions in binary form must reproduce the above copyright
12 // notice, this list of conditions and the following disclaimer in the
13 // documentation and/or other materials provided with the distribution.
15 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS
19 // BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
20 // OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
21 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
22 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
23 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
24 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
25 // THE POSSIBILITY OF SUCH DAMAGE.
32 // Service specification for the FRR northbound interface.
34 // Retrieve the capabilities supported by the target.
35 rpc GetCapabilities(GetCapabilitiesRequest) returns (GetCapabilitiesResponse) {}
37 // Retrieve configuration data, state data or both from the target.
38 rpc Get(GetRequest) returns (stream GetResponse) {}
40 // Create a new candidate configuration and return a reference to it. The
41 // created candidate is a copy of the running configuration.
42 rpc CreateCandidate(CreateCandidateRequest) returns (CreateCandidateResponse) {}
44 // Delete a candidate configuration.
45 rpc DeleteCandidate(DeleteCandidateRequest) returns (DeleteCandidateResponse) {}
47 // Update a candidate configuration by rebasing the changes on top of the
48 // latest running configuration. Resolve conflicts automatically by giving
49 // preference to the changes done in the candidate configuration.
50 rpc UpdateCandidate(UpdateCandidateRequest) returns (UpdateCandidateResponse) {}
52 // Edit a candidate configuration. All changes are discarded if any error
54 rpc EditCandidate(EditCandidateRequest) returns (EditCandidateResponse) {}
56 // Load configuration data into a candidate configuration. Both merge and
57 // replace semantics are supported.
58 rpc LoadToCandidate(LoadToCandidateRequest) returns (LoadToCandidateResponse) {}
60 // Create a new configuration transaction using a two-phase commit protocol.
61 rpc Commit(CommitRequest) returns (CommitResponse) {}
63 // List the metadata of all configuration transactions recorded in the
64 // transactions database.
65 rpc ListTransactions(ListTransactionsRequest) returns (stream ListTransactionsResponse) {}
67 // Fetch a configuration (identified by its transaction ID) from the
68 // transactions database.
69 rpc GetTransaction(GetTransactionRequest) returns (GetTransactionResponse) {}
71 // Lock the running configuration, preventing other users from changing it.
72 rpc LockConfig(LockConfigRequest) returns (LockConfigResponse) {}
74 // Unlock the running configuration.
75 rpc UnlockConfig(UnlockConfigRequest) returns (UnlockConfigResponse) {}
77 // Execute a YANG RPC.
78 rpc Execute(ExecuteRequest) returns (ExecuteResponse) {}
81 // ----------------------- Parameters and return types -------------------------
84 // RPC: GetCapabilities()
86 message GetCapabilitiesRequest {
90 message GetCapabilitiesResponse {
92 // - grpc::StatusCode::OK: Success.
95 string frr_version = 1;
97 // Indicates whether FRR was compiled with support for configuration
98 // rollbacks or not (--enable-config-rollbacks).
99 bool rollback_support = 2;
101 // Supported schema modules.
102 repeated ModuleData supported_modules = 3;
104 // Supported encodings.
105 repeated Encoding supported_encodings = 4;
112 // Type of elements within the data tree.
114 // All data elements.
124 // The type of data being requested.
127 // Encoding to be used.
128 Encoding encoding = 2;
130 // Include implicit default nodes.
131 bool with_defaults = 3;
133 // Paths requested by the client.
134 repeated string path = 4;
137 message GetResponse {
139 // - grpc::StatusCode::OK: Success.
140 // - grpc::StatusCode::INVALID_ARGUMENT: Invalid YANG data path.
142 // Timestamp in nanoseconds since Epoch.
145 // The requested data.
150 // RPC: CreateCandidate()
152 message CreateCandidateRequest {
156 message CreateCandidateResponse {
158 // - grpc::StatusCode::OK: Success.
159 // - grpc::StatusCode::RESOURCE_EXHAUSTED: can't create candidate
162 // Handle to the new created candidate configuration.
163 uint32 candidate_id = 1;
167 // RPC: DeleteCandidate()
169 message DeleteCandidateRequest {
170 // Candidate configuration to delete.
171 uint32 candidate_id = 1;
174 message DeleteCandidateResponse {
176 // - grpc::StatusCode::OK: Success.
177 // - grpc::StatusCode::NOT_FOUND: Candidate wasn't found.
181 // RPC: UpdateCandidate()
183 message UpdateCandidateRequest {
184 // Candidate configuration to update.
185 uint32 candidate_id = 1;
188 message UpdateCandidateResponse {
190 // - grpc::StatusCode::OK: Success.
191 // - grpc::StatusCode::NOT_FOUND: Candidate wasn't found.
195 // RPC: EditCandidate()
197 message EditCandidateRequest {
198 // Candidate configuration that is going to be edited.
199 uint32 candidate_id = 1;
201 // Data elements to be created or updated.
202 repeated PathValue update = 2;
204 // Paths to be deleted from the data tree.
205 repeated PathValue delete = 3;
208 message EditCandidateResponse {
210 // - grpc::StatusCode::OK: Success.
211 // - grpc::StatusCode::NOT_FOUND: Candidate wasn't found.
212 // - grpc::StatusCode::INVALID_ARGUMENT: An error occurred while editing the
213 // candidate configuration.
217 // RPC: LoadToCandidate()
219 message LoadToCandidateRequest {
221 // Merge the data tree into the candidate configuration.
224 // Replace the candidate configuration by the provided data tree.
228 // Candidate configuration that is going to be edited.
229 uint32 candidate_id = 1;
231 // Load operation to apply.
234 // Configuration data.
238 message LoadToCandidateResponse {
240 // - grpc::StatusCode::OK: Success.
241 // - grpc::StatusCode::INVALID_ARGUMENT: An error occurred while performing
242 // the load operation.
248 message CommitRequest {
250 // Validate if the configuration changes are valid (phase 0).
253 // Prepare resources to apply the configuration changes (phase 1).
256 // Release previously allocated resources (phase 2).
259 // Apply the configuration changes (phase 2).
262 // All of the above (VALIDATE + PREPARE + ABORT/APPLY).
264 // This option can't be used to implement network-wide transactions,
265 // since they require the manager entity to take into account the results
266 // of the preparation phase of multiple managed devices.
270 // Candidate configuration that is going to be committed.
271 uint32 candidate_id = 1;
273 // Transaction phase.
276 // Assign a comment to this commit.
280 message CommitResponse {
282 // - grpc::StatusCode::OK: Success.
283 // - grpc::StatusCode::FAILED_PRECONDITION: misuse of the two-phase commit
285 // - grpc::StatusCode::INVALID_ARGUMENT: Validation error.
286 // - grpc::StatusCode::RESOURCE_EXHAUSTED: Failure to allocate resource.
288 // ID of the created configuration transaction (when the phase is APPLY
290 uint32 transaction_id = 1;
292 // Human-readable error or warning message(s).
293 string error_message = 2;
297 // RPC: ListTransactions()
299 message ListTransactionsRequest {
303 message ListTransactionsResponse {
305 // - grpc::StatusCode::OK: Success.
310 // Client that committed the transaction.
313 // Date and time the transaction was committed.
316 // Comment assigned to the transaction.
321 // RPC: GetTransaction()
323 message GetTransactionRequest {
324 // Transaction to retrieve.
325 uint32 transaction_id = 1;
327 // Encoding to be used.
328 Encoding encoding = 2;
330 // Include implicit default nodes.
331 bool with_defaults = 3;
334 message GetTransactionResponse {
336 // - grpc::StatusCode::OK: Success.
337 // - grpc::StatusCode::NOT_FOUND: Transaction wasn't found in the transactions
346 message LockConfigRequest {
350 message LockConfigResponse {
352 // - grpc::StatusCode::OK: Success.
353 // - grpc::StatusCode::FAILED_PRECONDITION: Running configuration is
358 // RPC: UnlockConfig()
360 message UnlockConfigRequest {
364 message UnlockConfigResponse {
366 // - grpc::StatusCode::OK: Success.
367 // - grpc::StatusCode::FAILED_PRECONDITION: Running configuration isn't
374 message ExecuteRequest {
375 // Path of the YANG RPC or YANG Action.
379 repeated PathValue input = 2;
382 message ExecuteResponse {
384 // - grpc::StatusCode::OK: Success.
386 // Output parameters.
387 repeated PathValue output = 1;
390 // -------------------------------- Definitions --------------------------------
394 // Name of the YANG module;
397 // Organization publishing the module.
398 string organization = 2;
400 // Latest revision of the module;
404 // Supported encodings for YANG instance data.
410 // Path-value pair representing a data element.
419 // YANG instance data.
421 Encoding encoding = 1;