docs/developer-guide/bier-developer-guide.rst

   1 .. _bier-dev-guide:
   2
   3 BIER Developer Guide
   4 ====================
   5
   6 BIER Architecture
   7 -----------------
   8
   9 -  **Channel**
  10
  11    -  Channel (multicast flow) configuration and deploying information management.
  12
  13 -  **Common**
  14
  15    -  Common YANG models collection.
  16
  17 -  **Drivers**
  18
  19    -  South-bound NETCONF interface for BIER, it has implemented standard interface (ietf-bier).
  20       If your BFR's NETCONF interface is Non-standard, you should add your own interface for driver.
  21
  22 -  **Sbi-Adapter**
  23
  24    -  Adapter for different BIER south-bound NETCONF interfaces.
  25
  26 -  **Service**
  27
  28    -  Major processor function for BIER.
  29
  30 -  **Topomanager**
  31
  32    -  BIER topology management.
  33
  34
  35 BIER Feature
  36 ------------
  37
  38 -  **odl-bier-all**
  39
  40    -  This feature contains all other features/bundles of BIER project. If you
  41       install it, it provides all functions that the BIER project can support.
  42
  43 -  **odl-bier-models**
  44
  45    -  This feature contains all models of BIER project, such as ietf-bier,
  46       ietf-multicast-information and so on.
  47
  48 -  **odl-bier-topomanager**
  49
  50    -  This feature generates BIER's topology from network topology which discovered
  51       via OpenFlow Plugin.
  52
  53 -  **odl-bier-topomanager-api**
  54
  55    -  This feature provides all APIs about BIER topology.
  56
  57 -  **odl-bier-topomanager-rest**
  58
  59    -  This feature provides function of BIER topology management, such as configure
  60       BIER domain, sub-domain, nodes, and user can invoke these RPCs via RESTCONF.
  61
  62 -  **odl-bier-topomanager-ui**
  63
  64    -  This feature can display bier-topo-manager's APIs on UIs (odl-mdsal-apidocs and
  65       odl-dlux-yangui).
  66
  67 -  **odl-bier-topomanager-cli**
  68
  69    -  This feature provides Karaf commands for BIER topo-manager debugging, which is
  70       useful for troubleshooting.
  71
  72 -  **odl-bier-channel**
  73
  74    -  This feature provides function about multicast flow information configuration
  75       and deployment in BIER domain.
  76
  77 -  **odl-bier-channel-api**
  78
  79    -  This feature provides all APIs about multicast flow configuration and deployment.
  80
  81 -  **odl-bier-channel-rest**
  82
  83    -  This feature provides function of BIER multicast information management, such as configure
  84       multicast, deploying BFIR and BFER in BIER domain, and user can invoke these RPCs via RESTCONF.
  85
  86 -  **odl-bier-channel-ui**
  87
  88    -  This feature can display bier-channel's APIs on UIs (odl-mdsal-apidocs and odl-dlux-yangui).
  89
  90 -  **odl-bier-channel-cli**
  91
  92    -  This feature provides Karaf commands for bier-channel debugging, which is useful for
  93       troubleshooting.
  94
  95 -  **odl-bier-service**
  96
  97    -  This feature provides function which processing the result of BIER topo-mamager and BIER
  98       channel-mamager, and invoking south-bound-interface for driver.
  99
 100 -  **odl-bier-service-cli**
 101
 102    -  This feature provides Karaf commands for bier-service debugging, which is useful for
 103       troubleshooting.
 104
 105 -  **odl-bier-adapter**
 106
 107    -  This feature provides adapter for different BIER south-bound NETCONF
 108       interfaces, so all BFRs in BIER domain with different NETCONF
 109       configuration interfaces and they can operate normally together.
 110
 111 -  **odl-bier-driver**
 112
 113    -  This feature is south-bound NETCONF interface for BIER, it has implemented standard interface
 114       (ietf-bier). If your BFR's NETCONF interface is Non-standard, you should add your own
 115       interface for driver.
 116
 117 APIs in BIER
 118 ------------
 119
 120 The sections below give details about the configuration settings for
 121 the components that can be configured.
 122
 123 Topology Manager
 124 ~~~~~~~~~~~~~~~~
 125
 126 API Description
 127 ^^^^^^^^^^^^^^^
 128
 129 -  bier/topomanager/api/src/main/yang/bier-topology-api.yang
 130
 131    -  **load-topology**
 132
 133       -  Load BIER topology, and list all topo-name in all BIER topologies.
 134
 135    -  **configure-domain**
 136
 137       -  Configure domain in given BIER topology.
 138
 139    -  **configure-subdomain**
 140
 141       -  Configure sub-domain in given BIER domain and topology.
 142
 143    -  **configure-node**
 144
 145       -  Configure node information in given topology, which defined in ietf-bier,
 146          such as domains, sub-domains, bitstringlength, bfr-id, encapsulation-type, etc.
 147
 148    -  **delete-domain**
 149
 150       -  Delete given domain in given topology.
 151
 152    -  **delete-subdomain**
 153
 154       -  Delete given sub-domain in given domain and topology.
 155
 156    -  **delete-node**
 157
 158       -  Delete given node which be assigned to given sub-domain and domain in
 159          given topology.
 160
 161    -  **query-topology**
 162
 163       -  Query given topology in BIER topology, and then display this
 164          topology's detail, such as information of node and link.
 165
 166    -  **query-node**
 167
 168       -  Query given nodes in given topology, and then display these nodes'
 169          detail, such as information of node-name, router-id,
 170          termination-point list, BIER domain and sub-domain list, etc.
 171
 172    -  **query-link**
 173
 174       -  Query given link in given topology, and then display this link's detail.
 175
 176    -  **query-domain**
 177
 178       -  Query domain in given BIER topology, and then display the domain-id list.
 179
 180    -  **query-subdomain**
 181
 182       -  Query sub-domain in given domain and given topology, and then display
 183          the sub-domain-id list.
 184
 185    -  **query-subdomain-node**
 186
 187       -  Query nodes which have been assigned to given sub-domain and domain in given
 188          topology, and then display these nodes' details.
 189
 190    -  **query-subdomain-link**
 191
 192       -  Query links which have been assigned to given sub-domain and domain in given
 193          topology, and then display these links' details.
 194
 195
 196 Parameters Description
 197 ^^^^^^^^^^^^^^^^^^^^^^
 198
 199 -  **topology-id**
 200
 201    -  BIER topology identifier.
 202
 203 -  **node-id**
 204
 205    -  Node identifier in network topology.
 206
 207 -  **latitude**
 208
 209    -  Node’s latitude, default value is 0.
 210
 211 -  **longitude**
 212
 213    -  Node’s longitude, default value is 0.
 214
 215 -  **tp-id**
 216
 217    -  Termination point identifier.
 218
 219 -  **domain-id**
 220
 221    -  BIER domain identifier.
 222
 223 -  **encapsulation-type**
 224
 225    -  Base identity for BIER encapsulation. Default value is "bier-encapsulation-mpls".
 226
 227 -  **bitstringlength**
 228
 229    -  The bitstringlength type for imposition mode. It's value can be chosen from 64,
 230       128, 256, 512, 1024, 2048, and 4096.
 231
 232    -  The BitStringLength ("Imposition BitStringLength") and sub-domain ("Imposition
 233       sub-domain") to use when it imposes (as a BFIR) a BIER encapsulation on a
 234       particular set of packets.
 235
 236 -  **bfr-id**
 237
 238    -  BIER bfr identifier. BFR-id is a number in the range [1, 65535].
 239
 240    -  Bfr-id is unique within the sub-domain. A BFR-id is a small unstructured positive
 241       integer. For instance, if a particular BIER sub-domain contains 1, 374 BFRs, each
 242       one could be given a BFR-id in the range 1-1374.
 243
 244    -  If a given BFR belongs to more than one sub-domain, it may (though it need not)
 245       have a different BFR-id for each sub-domain.
 246
 247 -  **ipv4-bfr-prefix**
 248
 249    -  BIER BFR IPv4 prefix.
 250
 251    -  A BFR's BFR-Prefix MUST be an IP address (either IPv4 or IPv6) of the BFR, and MUST be
 252       unique and routable within the BIER domain. It is RECOMMENDED that the BFR-prefix be a
 253       loopback address of the BFR. Two BFRs in the same BIER domain MUST NOT be assigned the
 254       same BFR-Prefix. Note that a BFR in a given BIER domain has the same BFR-prefix in all
 255       the sub-domains of that BIER domain.
 256
 257 -  **ipv6-bfr-prefix**
 258
 259    -  BIER BFR IPv6 prefix.
 260
 261 -  **sub-domain-id**
 262
 263    -  Sub-domain identifier. Each sub-domain is identified by a sub-domain-id in the range [0, 255].
 264
 265    -  A BIER domain may contain one or more sub-domains. Each BIER domain MUST contain at least one
 266       sub-domain, the "default sub-domain" (also denoted "sub-domain zero"). If a BIER domain
 267       contains more than one sub-domain, each BFR in the domain MUST be provisioned to know the set
 268       of sub-domains to which it belongs.
 269
 270 -  **igp-type**
 271
 272    -  The IGP type. Enum type contains OSPF and ISIS.
 273
 274 -  **mt-id**
 275
 276    -  Multi-topology associated with BIER sub-domain.
 277
 278 -  **bitstringlength**
 279
 280    -  Disposition bitstringlength.
 281
 282    -  The BitStringLengths ("Disposition BitStringLengths") that it will process when
 283       (as a BFR or BFER) it receives packets from a particular sub-domain.
 284
 285 -  **bier-mpls-label-base**
 286
 287    -  BIER mpls-label, range in [0, 1048575].
 288
 289 -  **bier-mpls-label-range-size**
 290
 291    -  BIER mpls-label range size.
 292
 293 -  **link-id**
 294
 295    -  The identifier of a link in the topology.
 296
 297    -  A link is specific to a topology to which it belongs.
 298
 299
 300 -  **source-node**
 301
 302    -  Source node identifier, must be in same topology.
 303
 304 -  **source-tp**
 305
 306    -  Termination point within source node that terminates the link.
 307
 308 -  **dest-node**
 309
 310    -  Destination node identifier and must be in same topology.
 311
 312 -  **dest-tp**
 313
 314    -  Termination point within destination node that terminates the link.
 315
 316 -  **delay**
 317
 318    -  The link delay, default value is 0.
 319
 320 -  **loss**
 321
 322    -  The number of packet loss on the link and default value is 0.
 323
 324 Channel Manager
 325 ~~~~~~~~~~~~~~~
 326
 327 API Description
 328 ^^^^^^^^^^^^^^^
 329
 330 -  bier/channel/api/src/main/yang/bier-channel-api.yang
 331
 332    -  **get-channel**
 333
 334       -  Display all channel's names in given BIER topology.
 335
 336    -  **query-channel**
 337
 338       -  Query specific channel in given topology and display this channel's information (multicast
 339          flow information and related BFIR,BFER information).
 340
 341    -  **add-channel**
 342
 343       -  Create channel with multicast information in given BIER topology.
 344
 345    -  **modify-channel**
 346
 347       -  Modify the channel's information which created above.
 348
 349    -  **remove-channel**
 350
 351       -  Remove given channel in given topology.
 352
 353    -  **deploy-channel**
 354
 355       -  Deploy channel, and configure BFIR and BFERs about this multicast flow in given topology.
 356
 357 Parameters Description
 358 ^^^^^^^^^^^^^^^^^^^^^^
 359
 360 -  **topology-id**
 361
 362    -  BIER topology identifier.
 363
 364 -  **channel-name**
 365
 366    -  BIER channel (multicast flow information) name.
 367
 368 -  **src-ip**
 369
 370    -  The IPv4 of multicast source. The value set to zero means that the receiver interests in
 371       all source that relevant to one group.
 372
 373 -  **dst-group**
 374
 375    -  The IPv4 of multicast group.
 376
 377 -  **domain-id**
 378
 379    -  BIER domain identifier.
 380
 381 -  **sub-domain-id**
 382
 383    -  BIER sub-domain identifier.
 384
 385 -  **source-wildcard**
 386
 387    -  The wildcard information of source, in the range [1, 32].
 388
 389 -  **group-wildcard**
 390
 391    -  The wildcard information of multi-cast group, in the range [1, 32].
 392
 393 -  **ingress-node**
 394
 395    -  BFIR (Bit-Forwarding Ingress Router).
 396
 397 -  **ingress-bfr-id**
 398
 399    -  The bfr-id of BRIR.
 400
 401 -  **egress-node**
 402
 403    -  BFER (Bit-Forwarding Egress Router).
 404
 405 -  **egress-bfr-id**
 406
 407    -  The bfr-id of BRER.
 408
 409 .. note:: For more information about BIER terminology, see `YANG Data Model for BIER Protocol <https://datatracker.ietf.org/doc/draft-ietf-bier-bier-yang/?include_text=1>`_.
 410
 411
 412 Sample Configurations
 413 ---------------------
 414
 415 1. Configure Domain And Sub-domain
 416 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 417
 418 1.1. Configure Domain
 419 ^^^^^^^^^^^^^^^^^^^^^
 420
 421 **REST API** : *POST /restconf/operations/bier-topology-api:configure-domain*
 422
 423 **Sample JSON Data**
 424
 425 .. code:: json
 426
 427     {
 428          "input": {
 429             "topo-id": " flow:1" ,
 430             "domain ":[
 431                {
 432                   "domain-id": " 1",
 433                },
 434                {
 435                  "domain-id": " 2",
 436                }
 437             ]
 438         }
 439     }
 440
 441 1.2. Configure Sub-domain
 442 ^^^^^^^^^^^^^^^^^^^^^^^^^
 443
 444 **REST API** : *POST /restconf/operations/bier-topology-api:configure-subdomain*
 445
 446 **Sample JSON Data**
 447
 448 .. code:: json
 449
 450     {
 451         "input": {
 452             "topo-id": " flow:1" ,
 453             "domain-id":" 1",
 454             "sub-domain":[
 455                 {
 456                     "sub-domain-id":" 0",
 457                 },
 458                 {
 459                     "sub-domain-id":"1",
 460                 }
 461             ]
 462         }
 463     }
 464
 465 2. Configure BIER Node
 466 ~~~~~~~~~~~~~~~~~~~~~~
 467
 468 **REST API** : *POST /restconf/operations/bier-topology-api:configure-node*
 469
 470 **Sample JSON Data**
 471
 472 .. code:: json
 473
 474     {
 475         "input": {
 476             "topology-id": "flow:1",
 477             "node-id": "openflow:3",
 478             "domain": [
 479                 {
 480                     "domain-id": "2",
 481                     "bier-global": {
 482                         "sub-domain": [
 483                             {
 484                                 "sub-domain-id": "0",
 485                                 "igp-type": "ISIS",
 486                                 "mt-id": "1",
 487                                 "bfr-id": "3",
 488                                 "bitstringlength": "64-bit",
 489                                 "af": {
 490                                     "ipv4": [
 491                                         {
 492                                             "bitstringlength": "64",
 493                                             "bier-mpls-label-base": "56",
 494                                             "bier-mpls-label-range-size": "100"
 495                                         }
 496                                     ]
 497                                 }
 498                             }
 499                         ],
 500                         "encapsulation-type": "bier-encapsulation-mpls",
 501                         "bitstringlength": "64-bit",
 502                         "bfr-id": "33",
 503                         "ipv4-bfr-prefix": "192.168.1.1/24",
 504                         "ipv6-bfr-prefix": "1030:0:0:0:C9B4:FF12:48AA:1A2B/60"
 505                     }
 506                 }
 507             ]
 508         }
 509     }
 510
 511 3. Query BIER Topology Information
 512 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 513
 514 3.1. Load Topology
 515 ^^^^^^^^^^^^^^^^^^
 516
 517 **REST API** : *POST /restconf/operations/bier-topology-api:load-topology*
 518
 519 no request body.
 520
 521 3.2. Query Topology
 522 ^^^^^^^^^^^^^^^^^^^
 523
 524 **REST API** : *POST /restconf/operations/bier-topology-api:query-topology*
 525
 526 **Sample JSON Data**
 527
 528 .. code:: json
 529
 530     {
 531         "input": {
 532             "topo-id": " flow:1"
 533         }
 534     }
 535
 536 3.3. Query BIER Node
 537 ^^^^^^^^^^^^^^^^^^^^
 538
 539 **REST API** : *POST /restconf/operations/bier-topology-api:query-node*
 540
 541 **Sample JSON Data**
 542
 543 .. code:: json
 544
 545     {
 546         "input": {
 547              "topo-id": " flow:1",
 548              "node-id": "openflow:3"
 549          }
 550     }
 551
 552 3.4. Query BIER Link
 553 ^^^^^^^^^^^^^^^^^^^^
 554
 555 **REST API** : *POST /restconf/operations/bier-topology-api:query-link*
 556
 557 **Sample JSON Data**
 558
 559 .. code:: json
 560
 561     {
 562         "input": {
 563              "topo-id": " flow:1",
 564              "node-id": "openflow:3"
 565          }
 566     }
 567
 568 3.5. Query Domain
 569 ^^^^^^^^^^^^^^^^^
 570
 571 **REST API** : *POST /restconf/operations/bier-topology-api:query-domain*
 572
 573 **Sample JSON Data**
 574
 575 .. code:: json
 576
 577     {
 578         "input": {
 579              "topo-id": " flow:1"
 580          }
 581     }
 582
 583 3.6. Query Sub-domain
 584 ^^^^^^^^^^^^^^^^^^^^^
 585
 586 **REST API** : *POST /restconf/operations/bier-topology-api:query-subdomain*
 587
 588 **Sample JSON Data**
 589
 590 .. code:: json
 591
 592     {
 593         "input": {
 594              "topo-id": " flow:1",
 595              "domain-id": "1"
 596          }
 597     }
 598
 599 3.7. Query Sub-domain Node
 600 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 601
 602 **REST API** : *POST /restconf/operations/bier-topology-api:query-subdomain-node*
 603
 604 **Sample JSON Data**
 605
 606 .. code:: json
 607
 608     {
 609         "input": {
 610             "topology-id": "flow:1",
 611             "domain-id": "1",
 612             "sub-domain-id": "0"
 613         }
 614     }
 615
 616 3.8. Query Sub-domain Link
 617 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 618
 619 **REST API** : *POST /restconf/operations/bier-topology-api:query-subdomain-link*
 620
 621 **Sample JSON Data**
 622
 623 .. code:: json
 624
 625     {
 626         "input": {
 627             "topology-id": "flow:1",
 628             "domain-id": "1",
 629             "sub-domain-id": "0"
 630         }
 631     }
 632
 633 4. BIER Channel    Configuration
 634 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 635
 636 4.1. Configure Channel
 637 ^^^^^^^^^^^^^^^^^^^^^^
 638
 639 **REST API** : *POST /restconf/operations/bier-channel-api:add-channel*
 640
 641 **Sample JSON Data**
 642
 643 .. code:: json
 644
 645     {
 646         "input": {
 647             "topology-id": "flow:1",
 648             "name": "channel-1",
 649             "src-ip": "1.1.1.1",
 650             "dst-group": "224.1.1.1",
 651             "domain-id": "1",
 652             "sub-domain-id": "11",
 653             "source-wildcard": "24",
 654             "group-wildcard": "30"
 655         }
 656     }
 657
 658 4.2. Modify Channel
 659 ^^^^^^^^^^^^^^^^^^^
 660
 661 **REST API** : *POST /restconf/operations/bier-channel-api:modify-channel*
 662
 663 **Sample JSON Data**
 664
 665 .. code:: json
 666
 667     {
 668         "input": {
 669             "topology-id": "flow:1",
 670             "name": "channel-1",
 671             "src-ip": "2.2.2.2",
 672             "dst-group": "225.1.1.1",
 673             "domain-id": "1",
 674             "sub-domain-id": "11",
 675             "source-wildcard": "24",
 676             "group-wildcard": "30"
 677         }
 678     }
 679
 680 5. Deploy Channel
 681 ~~~~~~~~~~~~~~~~~
 682
 683 **REST API** : *POST /restconf/operations/bier-channel-api:deploy-channel*
 684
 685 **Sample JSON Data**
 686
 687 .. code:: json
 688
 689     {
 690         "input": {
 691             "topology-id": "flow:1",
 692             "channel-name": "channel-1",
 693             "ingress-node": "node1",
 694             "egress-node": [
 695                 {
 696                     "node-id": "node2"
 697                 },
 698                 {
 699                     "node-id": "node3"
 700                 }
 701             ]
 702         }
 703     }
 704
 705 6. Query Channel Information
 706 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 707
 708 6.1. Get Channel
 709 ^^^^^^^^^^^^^^^^
 710
 711 **REST API** : *POST /restconf/operations/bier-channel-api:get-channel*
 712
 713 **Sample JSON Data**
 714
 715 .. code:: json
 716
 717     {
 718         "input": {
 719             "topology-id": "flow:1"
 720         }
 721     }
 722
 723 6.2. Query Channel
 724 ^^^^^^^^^^^^^^^^^^
 725
 726 **REST API** : *POST /restconf/operations/bier-channel-api:query-channel*
 727
 728 **Sample JSON Data**
 729
 730 .. code:: json
 731
 732     {
 733         "input": {
 734             "topology-id": "flow:1",
 735             "channel-name": [
 736                 "channel-1",
 737                 "channel-2"
 738             ]
 739         }
 740     }
 741
 742 7. Remove Channel
 743 ~~~~~~~~~~~~~~~~~
 744
 745 **REST API** : *POST /restconf/operations/bier-channel-api:remove-channel*
 746
 747 **Sample JSON Data**
 748
 749 .. code:: json
 750
 751     {
 752         "input": {
 753             "topology-id": "flow:1",
 754             "channel-name": "channel-1"
 755         }
 756     }
 757
 758 8. Delete BIER Topology Configuration
 759 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 760
 761 8.1. Delete BIER Node
 762 ^^^^^^^^^^^^^^^^^^^^^
 763
 764 **REST API** : *POST /restconf/operations/bier-topology-api:delete-node*
 765
 766 **Sample JSON Data**
 767
 768 .. code:: json
 769
 770     {
 771          "input": {
 772                  "topo-id": "flow:1",
 773                  "node-id": " openflow:3",
 774                  "domain-id": "1",
 775                  "subdomain-id": "0"
 776         }
 777     }
 778
 779 8.2. Delete Sub-domain
 780 ^^^^^^^^^^^^^^^^^^^^^^
 781
 782 **REST API** : *POST /restconf/operations/bier-topology-api:delete-subdomian*
 783
 784 **Sample JSON Data**
 785
 786 .. code:: json
 787
 788     {
 789          "input": {
 790                  "topo-id": "flow:1",
 791                  "domain-id": "1",
 792                  "subdomain-id": "0"
 793         }
 794     }
 795
 796 8.3. Delete Domain
 797 ^^^^^^^^^^^^^^^^^^
 798
 799 **REST API** : *POST /restconf/operations/bier-topology-api:delete-domian*
 800
 801 **Sample JSON Data**
 802
 803 .. code:: json
 804
 805     {
 806          "input": {
 807                  "topo-id": "flow:1",
 808                  "domain-id": "1"
 809         }
 810     }