manuals/developer-guide/src/main/asciidoc/bgpcep/odl-bgpcep-pcep-all-dev.adoc

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