grpc/frr-northbound.proto

   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 }