docs/developer-guide/pcep-developer-guide.rst

   1 PCEP Developer Guide
   2 ====================
   3
   4 Overview
   5 --------
   6
   7 This section provides an overview of **feature odl-bgpcep-pcep-all** .
   8 This feature will install everything needed for PCEP (Path Computation
   9 Element Protocol) including establishing the connection, storing
  10 information about LSPs (Label Switched Paths) and displaying data in
  11 network-topology overview.
  12
  13 PCEP Architecture
  14 -----------------
  15
  16 Each feature represents a module in the BGPCEP codebase. The following
  17 diagram illustrates how the features are related.
  18
  19 .. figure:: ./images/bgpcep/pcep-dependency-tree.png
  20    :alt: PCEP Dependency Tree
  21
  22    PCEP Dependency Tree
  23
  24 Key APIs and Interfaces
  25 -----------------------
  26
  27 PCEP
  28 ~~~~
  29
  30 Session handling
  31 ^^^^^^^^^^^^^^^^
  32
  33 *32-pcep.xml* defines only pcep-dispatcher the parser should be using
  34 (global-pcep-extensions), factory for creating session proposals (you
  35 can create different proposals for different PCCs (Path Computation
  36 Clients)).
  37
  38 .. code:: xml
  39
  40      <module>
  41       <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:pcep:impl">prefix:pcep-dispatcher-impl</type>
  42       <name>global-pcep-dispatcher</name>
  43       <pcep-extensions>
  44        <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">pcepspi:extensions</type>
  45        <name>global-pcep-extensions</name>
  46       </pcep-extensions>
  47       <pcep-session-proposal-factory>
  48        <type xmlns:pcep="urn:opendaylight:params:xml:ns:yang:controller:pcep">pcep:pcep-session-proposal-factory</type>
  49        <name>global-pcep-session-proposal-factory</name>
  50       </pcep-session-proposal-factory>
  51       <boss-group>
  52        <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-threadgroup</type>
  53        <name>global-boss-group</name>
  54       </boss-group>
  55       <worker-group>
  56        <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-threadgroup</type>
  57        <name>global-worker-group</name>
  58       </worker-group>
  59      </module>
  60
  61 For user configuration of PCEP, check User Guide.
  62
  63 Parser
  64 ^^^^^^
  65
  66 The base PCEP parser includes messages and attributes from
  67 `RFC5441 <http://tools.ietf.org/html/rfc5441>`__,
  68 `RFC5541 <http://tools.ietf.org/html/rfc5541>`__,
  69 `RFC5455 <http://tools.ietf.org/html/rfc5455>`__,
  70 `RFC5557 <http://tools.ietf.org/html/rfc5557>`__ and
  71 `RFC5521 <http://tools.ietf.org/html/rfc5521>`__.
  72
  73 Registration
  74 ^^^^^^^^^^^^
  75
  76 All parsers and serializers need to be registered into *Extension
  77 provider*. This *Extension provider* is configured in initial
  78 configuration of the parser-spi module (*32-pcep.xml*).
  79
  80 .. code:: xml
  81
  82     <module>
  83      <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">prefix:pcep-extensions-impl</type>
  84      <name>global-pcep-extensions</name>
  85      <extension>
  86       <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">pcepspi:extension</type>
  87       <name>pcep-parser-base</name>
  88      </extension>
  89      <extension>
  90       <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">pcepspi:extension</type>
  91       <name>pcep-parser-ietf-stateful07</name>
  92      </extension>
  93      <extension>
  94       <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">pcepspi:extension</type>
  95       <name>pcep-parser-ietf-initiated00</name>
  96      </extension>
  97      <extension>
  98       <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">pcepspi:extension</type>
  99       <name>pcep-parser-sync-optimizations</name>
 100      </extension>
 101     </module>
 102
 103 -  *pcep-parser-base* - will register parsers and serializers
 104    implemented in pcep-impl module
 105
 106 -  *pcep-parser-ietf-stateful07* - will register parsers and serializers
 107    of draft-ietf-pce-stateful-pce-07 implementation
 108
 109 -  *pcep-parser-ietf-initiated00* - will register parser and serializer
 110    of draft-ietf-pce-pce-initiated-lsp-00 implementation
 111
 112 -  *pcep-parser-sync-optimizations* - will register parser and
 113    serializers of draft-ietf-pce-stateful-sync-optimizations-03
 114    implementation
 115
 116 Stateful07 module is a good example of a PCEP parser extension.
 117
 118 Configuration of PCEP parsers specifies one implementation of *Extension
 119 provider* that will take care of registering mentioned parser
 120 extensions:
 121 `SimplePCEPExtensionProviderContext <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/spi/src/main/java/org/opendaylight/protocol/pcep/spi/pojo/SimplePCEPExtensionProviderContext.java;hb=refs/for/stable/boron>`__.
 122 All registries are implemented in package
 123 `pcep-spi <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=tree;f=pcep/spi/src/main/java/org/opendaylight/protocol/pcep/spi/pojo;hb=refs/for/stable/boron>`__.
 124
 125 Parsing
 126 ^^^^^^^
 127
 128 Parsing of PCEP elements is mostly done equally to BGP, the only
 129 exception is message parsing, that is described here.
 130
 131 In BGP messages, parsing of first-level elements (path-attributes) can
 132 be validated in a simple way, as the attributes should be ordered
 133 chronologically. PCEP, on the other hand, has a strict object order
 134 policy, that is described in RBNF (Routing Backus-Naur Form) in each
 135 RFC. Therefore the algorithm for parsing here is to parse all objects in
 136 order as they appear in the message. The result of parsing is a list of
 137 *PCEPObjects*, that is put through validation. *validate()* methods are
 138 present in each message parser. Depending on the complexity of the
 139 message, it can contain either a simple condition (checking the presence
 140 of a mandatory object) or a full state machine.
 141
 142 In addition to that, PCEP requires sending error message for each
 143 documented parsing error. This is handled by creating an empty list of
 144 messages *errors* which is then passed as argument throughout whole
 145 parsing process. If some parser encounters *PCEPDocumentedException*, it
 146 has the duty to create appropriate PCEP error message and add it to this
 147 list. In the end, when the parsing is finished, this list is examined
 148 and all messages are sent to peer.
 149
 150 Better understanding provides this sequence diagram:
 151
 152 .. figure:: ./images/bgpcep/pcep-parsing.png
 153    :alt: Parsing
 154
 155    Parsing
 156
 157 PCEP IETF stateful
 158 ~~~~~~~~~~~~~~~~~~
 159
 160 This section summarizes module pcep-ietf-stateful07. The term *stateful*
 161 refers to
 162 `draft-ietf-pce-stateful-pce <http://tools.ietf.org/html/draft-ietf-pce-stateful-pce>`__
 163 and
 164 `draft-ietf-pce-pce-initiated-lsp <http://tools.ietf.org/html/draft-ietf-pce-pce-initiated-lsp>`__
 165 in versions draft-ietf-pce-stateful-pce-07 with
 166 draft-ietf-pce-pce-initiated-lsp-00.
 167
 168 We will upgrade our implementation, when the stateful draft gets
 169 promoted to RFC.
 170
 171 The stateful module is implemented as extensions to pcep-base-parser.
 172 The stateful draft declared new elements as well as additional fields or
 173 TLVs (type,length,value) to known objects. All new elements are defined
 174 in yang models, that contain augmentations to elements defined in
 175 `pcep-types.yang <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/api/src/main/yang/pcep-types.yang;hb=refs/for/stable/boron>`__.
 176 In the case of extending known elements, the *Parser* class merely
 177 extends the base class and overrides necessary methods as shown in
 178 following diagram:
 179
 180 .. figure:: ./images/bgpcep/validation.png
 181    :alt: Extending existing parsers
 182
 183    Extending existing parsers
 184
 185 All parsers (including those for newly defined PCEP elements) have to be
 186 registered via the *Activator* class. This class is present in both
 187 modules.
 188
 189 In addition to parsers, the stateful module also introduces additional
 190 session proposal. This proposal includes new fields defined in stateful
 191 drafts for Open object.
 192
 193 PCEP segment routing (SR)
 194 ~~~~~~~~~~~~~~~~~~~~~~~~~
 195
 196 PCEP Segment Routing is an extension of base PCEP and
 197 pcep-ietf-stateful-07 extension. The pcep-segment-routing module
 198 implements
 199 `draft-ietf-pce-segment-routing-01 <http://tools.ietf.org/html/draft-ietf-pce-segment-routing-01>`__.
 200
 201 The extension brings new SR-ERO (Explicit Route Object) and SR-RRO
 202 (Reported Route Object) subobject composed of SID (Segment Identifier)
 203 and/or NAI (Node or Adjacency Identifier). The segment Routing path is
 204 carried in the ERO and RRO object, as a list of SR-ERO/SR-RRO subobjects
 205 in an order specified by the user. The draft defines new TLV -
 206 SR-PCE-CAPABILITY TLV, carried in PCEP Open object, used to negotiate
 207 Segment Routing ability.
 208
 209 | The yang models of subobject, SR-PCE-CAPABILITY TLV and appropriate
 210   augmentations are defined in
 211   `odl-pcep-segment-routing.yang <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/segment-routing/src/main/yang/odl-pcep-segment-routing.yang;hb=refs/for/stable/boron>`__.
 212 | The pcep-segment-routing module includes parsers/serializers for new
 213   subobject
 214   (`SrEroSubobjectParser <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/segment-routing/src/main/java/org/opendaylight/protocol/pcep/segment/routing/SrEroSubobjectParser.java;hb=refs/for/stable/boron>`__)
 215   and TLV
 216   (`SrPceCapabilityTlvParser <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/segment-routing/src/main/java/org/opendaylight/protocol/pcep/segment/routing/SrPceCapabilityTlvParser.java;hb=refs/for/stable/boron>`__).
 217
 218 The pcep-segment-routing module implements
 219 `draft-ietf-pce-lsp-setup-type-01 <http://tools.ietf.org/html/draft-ietf-pce-lsp-setup-type-01>`__,
 220 too. The draft defines new TLV - Path Setup Type TLV, which value
 221 indicate path setup signaling technique. The TLV may be included in
 222 RP(Request Parameters)/SRP(Stateful PCE Request Parameters) object. For
 223 the default RSVP-TE (Resource Reservation Protocol), the TLV is omitted.
 224 For Segment Routing, PST = 1 is defined.
 225
 226 The Path Setup Type TLV is modeled with yang in module
 227 `pcep-types.yang <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/api/src/main/yang/pcep-types.yang;hb=refs/for/stable/boron>`__.
 228 A parser/serializer is implemented in
 229 `PathSetupTypeTlvParser <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/impl/src/main/java/org/opendaylight/protocol/pcep/impl/tlv/PathSetupTypeTlvParser.java;hb=refs/for/stable/boron>`__
 230 and it is overriden in segment-routing module to provide the aditional
 231 PST.
 232
 233 PCEP Synchronization Procedures Optimization
 234 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 235
 236 Optimizations of Label Switched Path State Synchronization Procedures
 237 for a Stateful PCE draft-ietf-pce-stateful-sync-optimizations-03
 238 specifies following optimizations for state synchronization and the
 239 corresponding PCEP procedures and extensions:
 240
 241 -  **State Synchronization Avoidance:** To skip state synchronization if
 242    the state has survived and not changed during session restart.
 243
 244 -  **Incremental State Synchronization:** To do incremental (delta)
 245    state synchronization when possible.
 246
 247 -  **PCE-triggered Initial Synchronization:** To let PCE control the
 248    timing of the initial state synchronization. The capability can be
 249    applied to both full and incremental state synchronization.
 250
 251 -  **PCE-triggered Re-synchronization:** To let PCE re-synchronize the
 252    state for sanity check.
 253
 254 PCEP Topology
 255 ~~~~~~~~~~~~~
 256
 257 PCEP data is displayed only through one URL that is accessible from the
 258 base network-topology URL:
 259
 260 *http://localhost:8181/restconf/operational/network-topology:network-topology/topology/pcep-topology*
 261
 262 Each PCC will be displayed as a node:
 263
 264 .. code:: xml
 265
 266     <node>
 267      <path-computation-client>
 268       <ip-address>42.42.42.42</ip-address>
 269       <state-sync>synchronized</state-sync>
 270       <stateful-tlv>
 271        <stateful>
 272         <initiation>true</initiation>
 273         <lsp-update-capability>true</lsp-update-capability>
 274        </stateful>
 275       </stateful-tlv>
 276      </path-computation-client>
 277      <node-id>pcc://42.42.42.42</node-id>
 278     </node>
 279     </source>
 280
 281 If some tunnels are configured on the network, they would be displayed
 282 on the same page, within a node that initiated the tunnel:
 283
 284 .. code:: xml
 285
 286     <node>
 287      <path-computation-client>
 288       <state-sync>synchronized</state-sync>
 289       <stateful-tlv>
 290        <stateful>
 291         <initiation>true</initiation>
 292         <lsp-update-capability>true</lsp-update-capability>
 293        </stateful>
 294       </stateful-tlv>
 295       <reported-lsp>
 296        <name>foo</name>
 297        <lsp>
 298         <operational>down</operational>
 299         <sync>false</sync>
 300         <ignore>false</ignore>
 301         <plsp-id>1</plsp-id>
 302         <create>false</create>
 303         <administrative>true</administrative>
 304         <remove>false</remove>
 305         <delegate>true</delegate>
 306         <processing-rule>false</processing-rule>
 307         <tlvs>
 308         <lsp-identifiers>
 309           <ipv4>
 310            <ipv4-tunnel-sender-address>43.43.43.43</ipv4-tunnel-sender-address>
 311            <ipv4-tunnel-endpoint-address>0.0.0.0</ipv4-tunnel-endpoint-address>
 312            <ipv4-extended-tunnel-id>0.0.0.0</ipv4-extended-tunnel-id>
 313           </ipv4>
 314           <tunnel-id>0</tunnel-id>
 315           <lsp-id>0</lsp-id>
 316          </lsp-identifiers>
 317          <symbolic-path-name>
 318           <path-name>Zm9v</path-name>
 319          </symbolic-path-name>
 320         </tlvs>
 321        </lsp>
 322       </reported-lsp>
 323       <ip-address>43.43.43.43</ip-address>
 324      </path-computation-client>
 325      <node-id>pcc://43.43.43.43</node-id>
 326     </node>
 327
 328 Note that, the *<path-name>* tag displays tunnel name in Base64
 329 encoding.
 330
 331 API Reference Documentation
 332 ---------------------------
 333
 334 Javadocs are generated while creating mvn:site and they are located in
 335 target/ directory in each module.
 336