src/plugins/ioam/ioam_plugin_doc.md

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