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

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