docs/pcep-developer-guide.rst

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