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>stateful07-proposal</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  </module>
  84 ----
  85
  86 * _pcep-parser-base_ - will register parsers and serializers
  87 implemented in pcep-impl module
  88
  89 * _pcep-parser-ietf-stateful07_ - will register parsers and
  90 serializers implemented in stateful07 module
  91
  92 Stateful07 module is a good example of a PCEP parser extension.
  93
  94 Configuration of PCEP parsers specifies one implementation of _Extension
  95 provider_ that will take care of registering mentioned parser
  96 extensions:
  97 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/lithium[SimplePCEPExtensionProviderContext].
  98 All registries are implemented in package
  99 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/lithium[pcep-spi].
 100
 101 ===== Parsing
 102
 103 Parsing of PCEP elements is mostly done equally to BGP,
 104 the only exception is message parsing, that is described here.
 105
 106 In BGP messages, parsing of first-level elements (path-attributes)
 107 can be validated in a simple way, as the attributes should be ordered
 108 chronologically. PCEP, on the other hand, has a strict object order
 109 policy, that is described in RBNF (Routing Backus-Naur Form) in each RFC.
 110 Therefore the algorithm for parsing here is to parse all objects in order
 111 as they appear in the message. The result of parsing is a list of _PCEPObjects_,
 112 that is put through validation. _validate()_ methods are present in each
 113 message parser. Depending on the complexity of the message, it can
 114 contain either a simple condition (checking the presence of a mandatory
 115 object) or a full state machine.
 116
 117 In addition to that, PCEP requires sending error message for each
 118 documented parsing error. This is handled by creating an empty list of
 119 messages _errors_ which is then passed as argument throughout whole
 120 parsing process. If some parser encounters _PCEPDocumentedException_,
 121 it has the duty to create appropriate PCEP error message and add it to
 122 this list. In the end, when the parsing is finished, this list is
 123 examined and all messages are sent to peer.
 124
 125 Better understanding provides this sequence diagram:
 126
 127 image::bgpcep/pcep-parsing.png[height="450px",width="550px",title="Parsing"]
 128
 129 ==== PCEP IETF stateful
 130
 131 This section summarizes module pcep-ietf-stateful07. The term
 132 _stateful_ refers to
 133 http://tools.ietf.org/html/draft-ietf-pce-stateful-pce[draft-ietf-pce-stateful-pce]
 134 and
 135 http://tools.ietf.org/html/draft-ietf-pce-pce-initiated-lsp[draft-ietf-pce-pce-initiated-lsp]
 136 in versions draft-ietf-pce-stateful-pce-07 with draft-ietf-pce-pce-initiated-lsp-00.
 137
 138 We will upgrade our implementation, when the stateful draft gets
 139 promoted to RFC.
 140
 141 The stateful module is implemented as extensions to pcep-base-parser.
 142 The stateful draft declared new elements as well as additional fields or
 143 TLVs (type,length,value) to known objects. All new elements are defined in yang models, that
 144 contain augmentations to elements defined in
 145 https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/api/src/main/yang/pcep-types.yang;hb=refs/for/stable/lithium[pcep-types.yang].
 146 In the case of extending known elements, the _Parser_ class merely extends
 147 the base class and overrides necessary methods as shown in following
 148 diagram:
 149
 150 image::bgpcep/validation.png[height="450px",width="550px",title="Extending existing parsers"]
 151
 152 All parsers (including those for newly defined PCEP elements) have to be
 153 registered via the _Activator_ class. This class is present in both modules.
 154
 155 In addition to parsers, the stateful module also introduces additional session
 156 proposal. This proposal includes new fields defined in stateful drafts
 157 for Open object.
 158
 159 ==== PCEP segment routing (SR)
 160
 161 PCEP Segment Routing is an extension of base PCEP and
 162 pcep-ietf-stateful-07 extension. The pcep-segment-routing module
 163 implements
 164 http://tools.ietf.org/html/draft-ietf-pce-segment-routing-01[draft-ietf-pce-segment-routing-01].
 165
 166 The extension brings new SR-ERO (Explicit Route Object) and SR-RRO (Reported Route Object)
 167 subobject composed of SID (Segment Identifier) and/or NAI (Node or Adjacency Identifier).
 168 The segment Routing path is carried in the ERO and RRO object, as a list of
 169 SR-ERO/SR-RRO subobjects in an order specified by the user. The draft defines new TLV -
 170 SR-PCE-CAPABILITY TLV, carried in PCEP Open object, used to negotiate Segment
 171 Routing ability.
 172
 173 The yang models of subobject, SR-PCE-CAPABILITY TLV and appropriate
 174 augmentations are defined in
 175 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/lithium[odl-pcep-segment-routing.yang]. +
 176 The pcep-segment-routing module includes parsers/serializers for new
 177 subobject
 178 (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/lithium[SrEroSubobjectParser])
 179 and TLV
 180 (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/lithium[SrPceCapabilityTlvParser]).
 181
 182 The pcep-segment-routing module implements
 183 http://tools.ietf.org/html/draft-ietf-pce-lsp-setup-type-01[draft-ietf-pce-lsp-setup-type-01],
 184 too. The draft defines new TLV - Path Setup Type TLV, which value
 185 indicate path setup signaling technique. The TLV may be included in
 186 RP(Request Parameters)/SRP(Stateful PCE Request Parameters) object.
 187 For the default RSVP-TE (Resource Reservation Protocol), the TLV is omitted.
 188 For Segment Routing, PST = 1 is defined.
 189
 190 The Path Setup Type TLV is modeled with yang in module
 191 https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/api/src/main/yang/pcep-types.yang;hb=refs/for/stable/lithium[pcep-types.yang].
 192 A parser/serializer is implemented in
 193 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/lithium[PathSetupTypeTlvParser]
 194 and it is overriden in segment-routing module to provide the aditional
 195 PST.
 196
 197 ==== PCEP Topology
 198
 199 PCEP data is displayed only through one URL that is accessible from the base network-topology URL:
 200
 201 _http://localhost:8181/restconf/operational/network-topology:network-topology/topology/pcep-topology_
 202
 203 Each PCC will be displayed as a node:
 204
 205 [source,xml]
 206 ----
 207 <node>
 208  <path-computation-client>
 209   <ip-address>42.42.42.42</ip-address>
 210   <state-sync>synchronized</state-sync>
 211   <stateful-tlv>
 212    <stateful>
 213     <initiation>true</initiation>
 214     <lsp-update-capability>true</lsp-update-capability>
 215    </stateful>
 216   </stateful-tlv>
 217  </path-computation-client>
 218  <node-id>pcc://42.42.42.42</node-id>
 219 </node>
 220 </source>
 221 ----
 222
 223 If some tunnels are configured on the network, they would be displayed on the same page, within a node that initiated the tunnel:
 224
 225 [source,xml]
 226 ----
 227 <node>
 228  <path-computation-client>
 229   <state-sync>synchronized</state-sync>
 230   <stateful-tlv>
 231    <stateful>
 232     <initiation>true</initiation>
 233     <lsp-update-capability>true</lsp-update-capability>
 234    </stateful>
 235   </stateful-tlv>
 236   <reported-lsp>
 237    <name>foo</name>
 238    <lsp>
 239     <operational>down</operational>
 240     <sync>false</sync>
 241     <ignore>false</ignore>
 242     <plsp-id>1</plsp-id>
 243     <create>false</create>
 244     <administrative>true</administrative>
 245     <remove>false</remove>
 246     <delegate>true</delegate>
 247     <processing-rule>false</processing-rule>
 248     <tlvs>
 249     <lsp-identifiers>
 250       <ipv4>
 251        <ipv4-tunnel-sender-address>43.43.43.43</ipv4-tunnel-sender-address>
 252        <ipv4-tunnel-endpoint-address>0.0.0.0</ipv4-tunnel-endpoint-address>
 253        <ipv4-extended-tunnel-id>0.0.0.0</ipv4-extended-tunnel-id>
 254       </ipv4>
 255       <tunnel-id>0</tunnel-id>
 256       <lsp-id>0</lsp-id>
 257      </lsp-identifiers>
 258      <symbolic-path-name>
 259       <path-name>Zm9v</path-name>
 260      </symbolic-path-name>
 261     </tlvs>
 262    </lsp>
 263   </reported-lsp>
 264   <ip-address>43.43.43.43</ip-address>
 265  </path-computation-client>
 266  <node-id>pcc://43.43.43.43</node-id>
 267 </node>
 268 ----
 269
 270 Note that, the _<path-name>_ tag displays tunnel name in Base64 encoding.
 271
 272 === API Reference Documentation
 273 Javadocs are generated while creating mvn:site
 274 and they are located in target/ directory in each module.