plugins/ioam-plugin/ioam/Readme.md

   1
   2 ## VPP Inband OAM (iOAM)
   3
   4 In-band OAM (iOAM) is an implementation study to record operational
   5 information in the packet while the packet traverses a path between
   6 two points in the network.
   7
   8 Overview of iOAM can be found in [iOAM-Devnet] page.
   9 The following IETF drafts detail the motivation and mechanism for
  10 recording operational information:
  11  - [iOAM-ietf-requirements] - Describes motivation and usecases for iOAM
  12  - [iOAM-ietf-data] - Describes data records that can be collected using iOAM
  13  - [iOAM-ietf-transport] - Lists out the transport protocols
  14  and mechanism to carry iOAM data records
  15  - [iOAM-ietf-proof-of-transit] - Describes the idea of Proof of Transit (POT)
  16  and mechanisms to operationalize the idea
  17
  18 ## Terminology
  19 In-band OAM is expected to be deployed in a specific domain rather
  20 than on the overall Internet. The part of the network which employs in-band OAM
  21 is referred to as **"in-band OAM-domain"**.
  22
  23 In-band OAM data is added to a packet on entering the in-band OAM-domain
  24 and is removed from the packet when exiting the domain.
  25 Within the in-band OAM-domain, network nodes that the packet traverses
  26 may update the in-band OAM data records.
  27
  28 - The node which adds in-band OAM data to the packet is called the
  29 **"in-band OAM encapsulating node"**.
  30
  31 - The node which removes the in-band OAM data is referred to as the
  32 **"in-band OAM decapsulating node"**.
  33
  34 - Nodes within the domain which are aware of in-band OAM data and read
  35 and/or write or process the in-band OAM data are called
  36 **"in-band OAM transit nodes"**.
  37
  38 ## Features supported in the current release
  39 VPP can function as in-band OAM encapsulating, transit and decapsulating node.
  40 In this version of VPP in-band OAM data is transported as options in an
  41 IPv6 hop-by-hop extension header. Hence in-band OAM can be enabled
  42 for IPv6 traffic.
  43
  44 The following iOAM features are supported:
  45
  46 - **In-band OAM Tracing** : In-band OAM supports multiple data records to be
  47 recorded in the packet as the packet traverses the network.
  48 These data records offer insights into the operational behavior of the network.
  49 The following information can be collected in the tracing
  50 data from the nodes a packet traverses:
  51   - Node ID
  52   - Ingress interface ID
  53   - Egress interface ID
  54   - Timestamp
  55   - Pre-configured application data
  56
  57 - **In-band OAM Proof of Transit (POT)**: Proof of transit iOAM data is
  58 added to every packet for verifying that a packet traverses a specific
  59 set of nodes.
  60 In-band OAM data is updated at every node that is enabled with iOAM
  61 proof of transit and is used to verify whether a packet traversed
  62 all the specified nodes. When the verifier receives each packet,
  63 it can validate whether the packet traversed the specified nodes.
  64
  65
  66 ## Configuration
  67 Configuring iOAM involves:
  68 - Selecting the packets for which iOAM data must be inserted, updated or removed
  69   - Selection of packets for iOAM data insertion on iOAM encapsulating node.
  70   Selection of packets is done by 5-tuple based classification
  71   - Selection of packets for updating iOAM data is implicitly done on the
  72   presence of iOAM options in the packet
  73   - Selection of packets for removing the iOAM data is done on 5-tuple
  74   based classification
  75 - The kind of data to be collected
  76   - Tracing data
  77   - Proof of transit
  78 - Additional details for processing iOAM data to be collected
  79   - For trace data - trace type, number of nodes to be recorded in the trace,
  80   time stamp precision, etc.
  81   - For POT data - configuration of POT profile required to process the POT data
  82
  83 The CLI for configuring iOAM is explained here followed by detailed steps
  84 and examples to deploy iOAM on VPP as an encapsulating, transit or
  85 decapsulating iOAM node in the subsequent sub-sections.
  86
  87 VPP iOAM configuration for enabling trace and POT is as follows:
  88
  89     set ioam rewrite trace-type <0x1f|0x7|0x9|0x11|0x19>
  90     trace-elts <number of trace elements> trace-tsp <0|1|2|3>
  91     node-id <node ID in hex> app-data <application data in hex> [pot]
  92
  93 A description of each of the options of the CLI follows:
  94 - trace-type : An entry in the "Node data List" array of the trace option
  95 can have different formats, following the needs of the a deployment.
  96 For example: Some deployments might only be interested
  97 in recording the node identifiers, whereas others might be interested
  98 in recording node identifier and timestamp.
  99 The following types are currently supported:
 100     - 0x1f : Node data to include hop limit (8 bits), node ID (24 bits),
 101     ingress and egress interface IDs (16 bits each), timestamp (32 bits),
 102     application data (32 bits)
 103     - 0x7 : Node data to include hop limit (8 bits), node ID (24 bits),
 104     ingress and egress interface IDs (16 bits each)
 105     - 0x9 : Node data to include hop limit (8 bits), node ID (24 bits),
 106     timestamp (32 bits)
 107     - 0x11: Node data to include hop limit (8 bits), node ID (24 bits),
 108     application data (32 bits)
 109     - 0x19: Node data to include hop limit (8 bits), node ID (24 bits),
 110     timestamp (32 bits), application data (32 bits)
 111 - trace-elts : Defines the length of the node data array in the trace option.
 112 - trace-tsp : Defines the timestamp precision to use with the enumerated value
 113               for precision as follows:
 114     - 0 : 32bits timestamp in seconds
 115     - 1 : 32bits timestamp in milliseconds
 116     - 2 : 32bits timestamp in microseconds
 117     - 3 : 32bits timestamp in nanoseconds
 118 - node-id : Unique identifier for the node, included in the node ID
 119   field of the node data in trace option.
 120 - app-data : The value configured here is included as is in
 121 application data field of node data in trace option.
 122 - pot : Enables POT option to be included in the iOAM options.
 123
 124 ### Trace configuration
 125
 126 #### On in-band OAM encapsulating node
 127  - **Configure classifier and apply ACL** to select packets for
 128  iOAM data insertion
 129     - Example to enable iOAM data insertion for all the packets
 130     towards IPv6 address db06::06:
 131
 132     vpp# classify table miss-next node ip6-lookup mask l3 ip6 dst
 133
 134     vpp# classify session acl-hit-next node ip6-add-hop-by-hop
 135     table-index 0 match l3 ip6 dst db06::06
 136
 137     vpp# set int input acl intfc GigabitEthernet0/0/0 ip6-table 0
 138
 139  - **Enable tracing** : Specify node ID, maximum number of nodes for which
 140  trace data should be recorded, type of data to be included for recording,
 141  optionally application data to be included
 142     - Example to enable tracing with a maximum of 4 nodes recorded
 143     and the data to be recorded to include - hop limit, node id,
 144     ingress and egress interface IDs, timestamp (millisecond precision),
 145     application data (0x1234):
 146
 147
 148     vpp# set ioam rewrite trace-type 0x1f trace-elts 4 trace-tsp 1
 149     node-id 0x1 app-data 0x1234
 150
 151
 152
 153 #### On in-band OAM transit node
 154 - The transit node requires trace type, timestamp precision, node ID and
 155 optionally application data to be configured,
 156 to update its node data in the trace option.
 157
 158 Example:
 159
 160     vpp# set ioam rewrite trace-type 0x1f trace-elts 4 trace-tsp 1
 161     node-id 0x2 app-data 0x1234
 162
 163 #### On the In-band OAM decapsulating node
 164 - The decapsulating node similar to encapsulating node requires
 165 **classification** of the packets to remove iOAM data from.
 166     - Example to decapsulate iOAM data for packets towards
 167     db06::06, configure classifier and enable it as an ACL as follows:
 168
 169
 170     vpp# classify table miss-next node ip6-lookup mask l3 ip6 dst
 171
 172     vpp# classify session acl-hit-next node ip6-lookup table-index 0
 173     match l3 ip6 dst db06::06 opaque-index 100
 174
 175     vpp# set int input acl intfc GigabitEthernet0/0/0 ip6-table 0
 176
 177
 178 - Decapsulating node requires trace type, timestamp precision,
 179 node ID and optionally application data to be configured,
 180 to update its node data in the trace option before it is decapsulated.
 181
 182 Example:
 183
 184     vpp# set ioam rewrite trace-type 0x1f trace-elts 4
 185     trace-tsp 1 node-id 0x3 app-data 0x1234
 186
 187
 188 ### Proof of Transit configuration
 189
 190 For details on proof-of-transit,
 191 see the IETF draft [iOAM-ietf-proof-of-transit].
 192 To enable Proof of Transit all the nodes that participate
 193 and hence are verified for transit need a proof of transit profile.
 194 A script to generate a proof of transit profile as per the mechanism
 195 described in [iOAM-ietf-proof-of-transit] will be available at [iOAM-Devnet].
 196
 197 The Proof of transit mechanism implemented here is based on
 198 Shamir's Secret Sharing algorithm.
 199 The overall algorithm uses two polynomials
 200 POLY-1 and POLY-2. The degree of polynomials depends on number of nodes
 201 to be verified for transit.
 202 POLY-1 is secret and constant. Each node gets a point on POLY-1
 203 at setup-time and keeps it secret.
 204 POLY-2 is public, random and per packet.
 205 Each node is assigned a point on POLY-1 and POLY-2 with the same x index.
 206 Each node derives its point on POLY-2 each time a packet arrives at it.
 207 A node then contributes its points on POLY-1 and POLY-2 to construct
 208 POLY-3 (POLY-3 = POLY-1 + POLY-2) using lagrange extrapolation and
 209 forwards it towards the verifier by updating POT data in the packet.
 210 The verifier constructs POLY-3 from the accumulated value from all the nodes
 211 and its own points on POLY-1 and POLY-2 and verifies whether
 212 POLY-3 = POLY-1 + POLY-2.  Only the verifier knows POLY-1.
 213 The solution leverages finite field arithmetic in a field of size "prime number"
 214 for reasons explained in description of Shamir's secret sharing algorithm.
 215
 216 Here is an explanation of POT profile list and profile configuration CLI to
 217 realize the above mechanism.
 218 It is best to use the script provided at [iOAM-Devnet] to generate
 219 this configuration.
 220 - **Create POT profile** : set pot profile name <string> id [0-1]
 221 [validator-key 0xu64] prime-number 0xu64 secret_share 0xu64
 222 lpc 0xu64 polynomial2 0xu64 bits-in-random [0-64]
 223     - name : Profile list name.
 224     - id : Profile id, it can be 0 or 1.
 225     A maximum of two profiles can be configured per profile list.
 226     - validator-key : Secret key configured only on the
 227     verifier/decapsulating node used to compare and verify proof of transit.
 228     - prime-number : Prime number for finite field arithmetic as required by the
 229     proof of transit mechanism.
 230     - secret_share : Unique point for each node on the secret polynomial POLY-1.
 231     - lpc : Lagrange Polynomial Constant(LPC) calculated per node based on
 232     its point (x value used for evaluating the points on the polynomial)
 233     on the polynomial used in lagrange extrapolation
 234     for reconstructing polynomial (POLY-3).
 235     - polynomial2 : Is the pre-evaluated value of the point on
 236     2nd polynomial(POLY-2). This is unique for each node.
 237     It is pre-evaluated for all the coefficients of POLY-2 except
 238     for the constant part of the polynomial that changes per packet
 239     and is received as part of the POT data in the packet.
 240     - bits-in-random : To control the size of the random number to be
 241     generated. This number has to match the other numbers generated and used
 242     in the profile as per the algorithm.
 243
 244 - **Set a configured profile as active/in-use** :
 245 set pot profile-active name <string> ID [0-1]
 246     - name : Name of the profile list to be used for computing
 247     POT data per packet.
 248     - ID : Identifier of the profile within the list to be used.
 249
 250 #### On In-band OAM encapsulating node
 251  - Configure the classifier and apply ACL to select packets for iOAM data insertion.
 252     - Example to enable iOAM data insertion for all the packet towards
 253     IPv6 address db06::06 -
 254
 255
 256     vpp# classify table miss-next node ip6-lookup mask l3 ip6 dst
 257
 258     vpp# classify session acl-hit-next node
 259     ip6-add-hop-by-hop table-index 0 match l3 ip6 dst db06::06
 260
 261     vpp# set int input acl intfc GigabitEthernet0/0/0 ip6-table 0
 262
 263
 264  - Configure the proof of transit profile list with profiles.
 265 Each profile list referred to by a name can contain 2 profiles,
 266 only one is in use for updating proof of transit data at any time.
 267     - Example profile list example with a profile generated from the
 268     script to verify transit through 3 nodes is:
 269
 270
 271     vpp# set pot profile name example id 0 prime-number 0x7fff0000fa884685
 272     secret_share 0x6c22eff0f45ec56d lpc 0x7fff0000fa884682
 273     polynomial2 0xffb543d4a9c bits-in-random 63
 274
 275  - Enable one of the profiles from the configured profile list as active
 276  so that is will be used for calculating proof of transit
 277
 278 Example enable profile ID 0 from profile list example configured above:
 279
 280
 281     vpp# set pot profile-active name example ID 0
 282
 283
 284  - Enable POT option to be inserted
 285
 286
 287     vpp# set ioam rewrite pot
 288
 289
 290 #### On in-band OAM transit node
 291  - Configure the proof of transit profile list with profiles for transit node.
 292 Example:
 293
 294
 295     vpp# set pot profile name example id 0 prime-number 0x7fff0000fa884685
 296     secret_share 0x564cdbdec4eb625d lpc 0x1
 297     polynomial2 0x23f3a227186a bits-in-random 63
 298
 299 #### On in-band OAM decapsulating node / verifier
 300 - The decapsulating node, similar to the encapsulating node requires
 301 classification of the packets to remove iOAM data from.
 302     - Example to decapsulate iOAM data for packets towards db06::06
 303     configure classifier and enable it as an ACL as follows:
 304
 305
 306     vpp# classify table miss-next node ip6-lookup mask l3 ip6 dst
 307
 308     vpp# classify session acl-hit-next node ip6-lookup table-index 0
 309     match l3 ip6 dst db06::06 opaque-index 100
 310
 311     vpp# set int input acl intfc GigabitEthernet0/0/0 ip6-table 0
 312
 313 - To update and verify the proof of transit, POT profile list should be configured.
 314     - Example POT profile list configured as follows:
 315
 316     vpp# set pot profile name example id 0 validate-key 0x7fff0000fa88465d
 317     prime-number 0x7fff0000fa884685 secret_share 0x7a08fbfc5b93116d lpc 0x3
 318     polynomial2 0x3ff738597ce bits-in-random 63
 319
 320 ## Operational data
 321
 322 Following CLIs are available to check iOAM operation:
 323 - To check iOAM configuration that are effective use "show ioam summary"
 324
 325 Example:
 326
 327     vpp# show ioam summary
 328                   REWRITE FLOW CONFIGS - Not configured
 329      HOP BY HOP OPTIONS - TRACE CONFIG -
 330                             Trace Type : 0x1f (31)
 331              Trace timestamp precision : 1 (Milliseconds)
 332                     Num of trace nodes : 4
 333                                Node-id : 0x2 (2)
 334                               App Data : 0x1234 (4660)
 335                             POT OPTION - 1 (Enabled)
 336     Try 'show ioam pot and show pot profile' for more information
 337
 338 - To find statistics about packets for which iOAM options were
 339 added (encapsulating node) and removed (decapsulating node) execute
 340 *show errors*
 341
 342 Example on encapsulating node:
 343
 344
 345     vpp# show error
 346        Count                    Node                  Reason
 347     1208804706                ip6-inacl               input ACL hits
 348     1208804706           ip6-add-hop-by-hop           Pkts w/ added ip6 hop-by-hop options
 349
 350 Example on decapsulating node:
 351
 352     vpp# show error
 353        Count                    Node                  Reason
 354       69508569                ip6-inacl               input ACL hits
 355       69508569           ip6-pop-hop-by-hop           Pkts w/ removed ip6 hop-by-hop options
 356
 357 - To check the POT profiles use "show pot profile"
 358
 359 Example:
 360
 361     vpp# show pot profile
 362     Profile list in use  : example
 363     POT Profile at index: 0
 364                      ID : 0
 365               Validator : False (0)
 366            Secret share : 0x564cdbdec4eb625d (6218586935324795485)
 367            Prime number : 0x7fff0000fa884685 (9223090566081300101)
 368     2nd polynomial(eval) : 0x23f3a227186a (39529304496234)
 369                      LPC : 0x1 (1)
 370                Bit mask : 0x7fffffffffffffff (9223372036854775807)
 371     Profile index in use: 0
 372     Pkts passed : 0x36 (54)
 373
 374 - To get statistics  of POT for packets use "show ioam pot"
 375
 376 Example at encapsulating or transit node:
 377
 378     vpp# show ioam pot
 379      Pkts with ip6 hop-by-hop POT options - 54
 380      Pkts with ip6 hop-by-hop POT options but no profile set - 0
 381      Pkts with POT in Policy - 0
 382      Pkts with POT out of Policy - 0
 383
 384
 385 Example at decapsulating/verification node:
 386
 387
 388     vpp# show ioam pot
 389      Pkts with ip6 hop-by-hop POT options - 54
 390      Pkts with ip6 hop-by-hop POT options but no profile set - 0
 391      Pkts with POT in Policy - 54
 392      Pkts with POT out of Policy - 0
 393
 394 - Tracing - enable trace of IPv6 packets to view the data inserted and
 395 collected.
 396
 397 Example when the nodes are receiving data over a DPDK interface:
 398 Enable tracing using "trace add dpdk-input 20" and
 399 execute "show trace" to view the iOAM data collected:
 400
 401
 402     vpp# trace add dpdk-input 20
 403
 404     vpp# show trace
 405
 406     ------------------- Start of thread 0 vpp_main -------------------
 407
 408     Packet 1
 409
 410     00:00:19:294697: dpdk-input
 411       GigabitEthernetb/0/0 rx queue 0
 412       buffer 0x10e6b: current data 0, length 214, free-list 0, totlen-nifb 0, trace 0x0
 413       PKT MBUF: port 0, nb_segs 1, pkt_len 214
 414         buf_len 2176, data_len 214, ol_flags 0x0, data_off 128, phys_addr 0xe9a35a00
 415         packet_type 0x0
 416       IP6: 00:50:56:9c:df:72 -> 00:50:56:9c:be:55
 417       IP6_HOP_BY_HOP_OPTIONS: db05::2 -> db06::6
 418         tos 0x00, flow label 0x0, hop limit 63, payload length 160
 419     00:00:19:294737: ethernet-input
 420       IP6: 00:50:56:9c:df:72 -> 00:50:56:9c:be:55
 421     00:00:19:294753: ip6-input
 422       IP6_HOP_BY_HOP_OPTIONS: db05::2 -> db06::6
 423         tos 0x00, flow label 0x0, hop limit 63, payload length 160
 424     00:00:19:294757: ip6-lookup
 425       fib 0 adj-idx 15 : indirect via db05::2 flow hash: 0x00000000
 426       IP6_HOP_BY_HOP_OPTIONS: db05::2 -> db06::6
 427         tos 0x00, flow label 0x0, hop limit 63, payload length 160
 428     00:00:19:294802: ip6-hop-by-hop
 429       IP6_HOP_BY_HOP: next index 5 len 96 traced 96  Trace Type 0x1f , 1 elts left
 430         [0] ttl 0x0 node ID 0x0 ingress 0x0 egress 0x0 ts 0x0
 431     app 0x0
 432         [1] ttl 0x3e node ID 0x3 ingress 0x1 egress 0x2 ts 0xb68c2213
 433     app 0x1234
 434         [2] ttl 0x3f node ID 0x2 ingress 0x1 egress 0x2 ts 0xb68c2204
 435     app 0x1234
 436         [3] ttl 0x40 node ID 0x1 ingress 0x5 egress 0x6 ts 0xb68c2200
 437     app 0x1234
 438         POT opt present
 439              random = 0x577a916946071950, Cumulative = 0x10b46e78a35a392d, Index = 0x0
 440     00:00:19:294810: ip6-rewrite
 441       tx_sw_if_index 1 adj-idx 14 : GigabitEthernetb/0/0
 442                                     IP6: 00:50:56:9c:be:55 -> 00:50:56:9c:df:72 flow hash: 0x00000000
 443       IP6: 00:50:56:9c:be:55 -> 00:50:56:9c:df:72
 444       IP6_HOP_BY_HOP_OPTIONS: db05::2 -> db06::6
 445         tos 0x00, flow label 0x0, hop limit 62, payload length 160
 446     00:00:19:294814: GigabitEthernetb/0/0-output
 447       GigabitEthernetb/0/0
 448       IP6: 00:50:56:9c:be:55 -> 00:50:56:9c:df:72
 449       IP6_HOP_BY_HOP_OPTIONS: db05::2 -> db06::6
 450         tos 0x00, flow label 0x0, hop limit 62, payload length 160
 451     00:00:19:294820: GigabitEthernetb/0/0-tx
 452       GigabitEthernetb/0/0 tx queue 0
 453       buffer 0x10e6b: current data 0, length 214, free-list 0, totlen-nifb 0, trace 0x0
 454       IP6: 00:50:56:9c:be:55 -> 00:50:56:9c:df:72
 455
 456       IP6_HOP_BY_HOP_OPTIONS: db05::2 -> db06::6
 457
 458         tos 0x00, flow label 0x0, hop limit 62, payload length 160
 459
 460
 461 [iOAM-Devnet]: <https://github.com/ciscodevnet/iOAM>
 462 [iOAM-ietf-requirements]:<https://tools.ietf.org/html/draft-brockners-inband-oam-requirements-01>
 463 [iOAM-ietf-transport]:<https://tools.ietf.org/html/draft-brockners-inband-oam-transport-01>
 464 [iOAM-ietf-data]:<https://tools.ietf.org/html/draft-brockners-inband-oam-data-01>
 465 [iOAM-ietf-proof-of-transit]:<https://tools.ietf.org/html/draft-brockners-proof-of-transit-01>