{"id":20589276,"url":"https://github.com/ciscodevnet/ioam","last_synced_at":"2025-04-14T22:05:52.721Z","repository":{"id":52705374,"uuid":"57926203","full_name":"CiscoDevNet/iOAM","owner":"CiscoDevNet","description":null,"archived":false,"fork":false,"pushed_at":"2021-04-20T17:14:54.000Z","size":55657,"stargazers_count":28,"open_issues_count":6,"forks_count":11,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-04-14T22:05:37.619Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CiscoDevNet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-05-02T22:51:27.000Z","updated_at":"2023-08-18T06:09:49.000Z","dependencies_parsed_at":"2022-08-22T10:21:24.372Z","dependency_job_id":null,"html_url":"https://github.com/CiscoDevNet/iOAM","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CiscoDevNet%2FiOAM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CiscoDevNet%2FiOAM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CiscoDevNet%2FiOAM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CiscoDevNet%2FiOAM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CiscoDevNet","download_url":"https://codeload.github.com/CiscoDevNet/iOAM/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248968833,"owners_count":21191160,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T07:28:33.736Z","updated_at":"2025-04-14T22:05:52.705Z","avatar_url":"https://github.com/CiscoDevNet.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# In-Situ OAM (IOAM)\n\nIn-situ OAM (sometimes also referred to as inband OAM, which was the term originally used before IETF chose \"in-situ OAM\" for the technology) is a technology to record operational\ninformation in the packet while the packet traverses a path between two points\nin the network. In-situ OAM is to complement current out-of-band OAM (sometimes also called \"active\" OAM) mechanisms based on ICMP or other types of probe\npackets.\n   \n# Overview\n\n\"In-situ\" OAM describes an approach to record OAM and telemetry information\nwithin the data packet while the data packet traverses a network or a\nparticular network domain.  The term \"in-situ\" refers to the fact that the OAM\nand telemetry data is carried within data packets rather than being sent\nwithin packets specifically dedicated to OAM.  In-situ OAM mechanisms, which\nare sometimes also referred to as embedded network telemetry are a current\ntopic of discussion.  In-band network telemetry has been defined for [P4].  The\nSPUD prototype [SPUD] uses a similar logic that allows\nnetwork devices on the path between endpoints to participate explicitly in the\ntube outside the end-to-end context.  Even the IPv4 route-record option defined\nin [RFC0791] can be considered an in-situ OAM mechanism.  In-situ OAM\ncomplements \"out-of-band\" mechanisms such as ping or traceroute, or more recent\nactive probing mechanisms, as described in [I-D.lapukhov-dataplane-probe].\nIn-situ OAM mechanisms can be leveraged where current out-of-band mechanisms do\nnot apply or do not offer the desired characteristics or requirements, such as\nproving that a certain set of traffic takes a pre-defined path,\nstrict congruency is desired, checking service level agreements for\nthe live data traffic, detailed statistics on traffic distribution\npaths in networks that distribute traffic across multiple paths, or\nscenarios where probe traffic is potentially handled differently from\nregular data traffic by the network devices.  [RFC7276] presents an\noverview of OAM tools.\n\nCompared to probably the most basic example of \"in-situ OAM\" which is\nIPv4 route recording [RFC0791], an in-situ OAM approach has the\nfollowing capabilities:\n\n- A flexible data format to allow different types of information to\n  be captured as part of an in-situ OAM operation, including not\n  only path tracing information, but additional operational and\n  telemetry information such as timestamps, sequence numbers, or\n  even generic data such as queue size, geo-location of the node\n  that forwarded the packet, etc.\n\n- A data format to express node as well as link identifiers to\n  record the path a packet takes with a fixed amount of added data.\n\n- The ability to detect whether any nodes were skipped while\n  recording in-situ OAM information (i.e., in-situ OAM is not\n  supported or not enabled on those nodes).\n   \n- The ability to actively process information in the packet, for\n  example to prove in a cryptographically secure way that a packet\n  really took a pre-defined path using some traffic steering method\n  such as service chaining or traffic engineering.\n\n- The ability to include OAM data beyond simple path information,\n  such as timestamps or even generic data of a particular use case.\n\n- The ability to include OAM data in various different transport\n  protocols.\n\nA detailed description in-situ OAM concepts, capabilities,\ndata-formats and transport encapsulations can be found in the\nfollowing IETF internet drafts:\n\n- [Requirements for In-band\n  OAM](https://tools.ietf.org/html/draft-brockners-inband-oam-requirements-03)\n  discusses the motivation and requirements for including\n  specific operational and telemetry information into data packets\n  while the data packet traverses a path between two points in the\n  network.\n\n- [Data Formats for In-Situ\n  OAM](https://tools.ietf.org/html/draft-ietf-ippm-ioam-data-06)\n  discusses the data types and data formats for in-situ OAM data\n  records.\n\n- Encapsulations for IOAM data. These drafts describe how IOAM data fields\n  are encapsulated in \"parent\" protocols: \n   - [NSH encapsulation for IOAM data](https://tools.ietf.org/html/draft-ietf-sfc-ioam-nsh-01)\n   - [Geneve encapsulation for IOAM data](https://tools.ietf.org/html/draft-brockners-ippm-ioam-geneve-02)\n   - [VXLAN-GPE encapsulation for IOAM data](https://tools.ietf.org/html/draft-brockners-ippm-ioam-vxlan-gpe-02)\n   - [IPv6 encapsulation for IOAM data](https://tools.ietf.org/html/draft-ioametal-ippm-6man-ioam-ipv6-options-01)\n   - [SRv6 encapsulation for IOAM data](https://tools.ietf.org/html/draft-ali-spring-ioam-srv6-01)\n   - [Encapsulations for protocols which use Ethertype for next protocol (e.g. GRE, Geneve)](https://tools.ietf.org/html/draft-weis-ippm-ioam-eth-01). Note: For IPv4, it\n  is suggested to use a GRE header sequenced in with an IOAM header to carry IOAM data fields.\n\n- [Proof of\n  Transit](https://tools.ietf.org/html/draft-ietf-sfc-proof-of-transit-02)\n  defines mechanisms to securely prove that traffic transited the defined path.\n  Several technologies such as traffic engineering, service function\n  chaining, or policy based routing, are used to steer traffic through\n  a specific, user-defined path.  The mechanisms described in this \n  document allow to securely verify whether all packets traversed all\n  those nodes of a given path that they are supposed to visit.\n\n- [Export of IOAM data in raw format](https://www.ietf.org/id/draft-spiegel-ippm-ioam-rawexport-00.txt) describes how IOAM information can be exported in raw, i.e. uninterpreted, format from network devices to systems, such as monitoring or analytics systems using IPFIX.\n\nA wide variety of use-cases can leverage IOAM:\n\n* Service/Quality Assurance - Fabric OAM\n  * Prove traffic SLAs, as opposed to probe-traffic SLAs; Overlay/Underlay\n  * Service/Path Verification (Proof of Transit) - prove that\n    traffic follows a pre-defined path\n* Micro-Service/NFV deployments\n  * Smart service selection based on network criteria - \"M-Anycast\"\n    (intelligent micro-service selection and load-balancing):\n    https://github.com/CiscoDevNet/iOAM/tree/master/M-Anycast.\n    For the VPP implementation of m-anycast, see https://docs.fd.io/vpp/17.04/ioam_manycast_doc.html\n* Operations Support - Fabric Visibility\n  * Network Fault Detection and Fault Isolation through\n    efficient network probing: By using IOAM's loopback option\n    an issue can be identified within a single packet roundtrip time.\n  * Path Tracing - debug ECMP, brown-outs, network delays\n  * Derive Traffic Matrix\n  * Custom/Service Level Telemetry \n\n# Code\n\n## Dataplane implementation in FD.io/VPP\n\n- The in-situ OAM dataplane is implemented as a plugin in VPP:\n  https://git.fd.io/cgit/vpp/tree/plugins/ioam-plugin.\n- Documentation for the in-situ OAM in VPP:\n  - Overview user guide: https://docs.fd.io/vpp/16.12/md_plugins_ioam-plugin_ioam_Readme.html\n  - Command line references:\n    - https://docs.fd.io/vpp/17.04/ioam_plugin_doc.html\n    - https://docs.fd.io/vpp/16.12/plugins_ioam-plugin_ioam_encap.html\n    - https://docs.fd.io/vpp/16.12/plugins_ioam-plugin_ioam_export.html\n    - https://docs.fd.io/vpp/16.12/plugins_ioam-plugin_ioam_lib-pot.html\n    - https://docs.fd.io/vpp/16.12/plugins_ioam-plugin_ioam_lib-trace.html\n- FD.io wiki on in-situ OAM configuration: https://wiki.fd.io/view/VPP/Command-line_Interface_(CLI)_Guide#Inline_IPv6_OAM_Commands.\n\n## Dataplane implementation in the Linux Kernel\n\nThe University of Liege in Belgium created an IOAM implementation for the Linux Kernel:\nhttps://github.com/IurmanJ/kernel_ipv6_ioam\n\n## Dataplane implementation in Cisco IOS\n\nThe dataplane implementation in Cisco IOS is focused on IPv6 only.\n\n- Documentation for in-situ OAM is found in the [In-band OAM for\n   IPv6](http://www.cisco.com/c/en/us/td/docs/ios-xml/ios/ipv6_nman/configuration/15-mt/ip6n-15-mt-book/ioam-ipv6.html) guide of the\n\"IPv6 Network Management Configuration Guide, Cisco IOS Release\n15M\u0026T\". \n- The IOS software can be downloaded from [here](https://software.cisco.com/download/navigator.html?mdfid=282774227\u0026flowid=78210).\nIPv6 in-situ OAM is supported on Cisco 1900/2900/3900/3900e Integrated Services Routers and vIOS on Cisco [VIRL] (http://virl.cisco.com/).\n\n- To configure Proof-of-Transit for IOS, a series of \n  configuration parameters are needed. To help with\n  computing the appropriate values, you can use the\n  scripts provided here, see\nhttps://github.com/CiscoDevNet/iOAM/tree/master/scripts/config_generator.\n  Note that those apply mostly for the IOS dataplane application.\n  For VPP, one can use the App for OpenDaylight.\n\n## In-band OAM Controller Application in OpenDaylight\n\nIn-band OAM is reflected in two applications within OpenDaylight:\n\n- *SFC*: In-band OAM \"Proof of Transit\" can be used as part of \n  OpenDaylight Service Function Chaining (SFC). The extensions to \n  ODL SFC enable ODL to serve POT control data (secrets etc.) required\n  for POT. Full support is expected as part of the OpenDaylight Carbon release.\n\n  - The following features are supported.\n    - Utilizes Java-based libraries to generate iOAM parameters.\n    - REST/Yang based APIs for north-bound to configure iOAM via OSS like postman or via programmatic triggers.\n    - Augments and enhances base SFC application.\n    - NETCONF/Yang based APIs for south-bound.\n    - Feature capability is split into two modules to be installed: sfc-pot and sfc-pot-netconf-renderer.\n  - The following are the feature commits.\n    -  https://git.opendaylight.org/gerrit/#/c/40669/\n    -  https://git.opendaylight.org/gerrit/#/c/48766/\n    -  https://git.opendaylight.org/gerrit/#/c/49636/\n    \n- *Path-tracing*: Configuration application to enable and control in-situ OAM tracing.\n  The tracing application will be included in a future version of\n  OpenDaylight as a separate module.  For now, it is dependent on the SFC git (but not SFC functionality) and is available as below.\n    - https://github.com/CiscoDevNet/iOAM/tree/master/sfc\n  \n## In-band OAM Configuration Agent in Honeycomb\n\nHoneycomb is a java-based agent that runs on the same host as a VPP instance, and exposes yang models via netconf or restconf to allow the management of that VPP instance from off box controllers like OpenDaylight.  The iOAM module in the Honeycomb agent helps exposes NETCONF and RESTCONF interfaces to allow iOAM trace and SFC verification features supported in the VPP instance behind it.\n\n- *Path-tracing*: Configuration agent application to enable and control in-situ OAM tracing.\n  - The following are the feature commits.\n    - https://gerrit.fd.io/r/#/c/3607/\n    - https://gerrit.fd.io/r/#/c/4215/\n- *Proof-of-Transit*: Configuration agent application to enable and control in-situ OAM Proof of Transit.\n  - The following are the feature commits.\n    - https://gerrit.fd.io/r/#/c/4268\n\n# Additional Resources\n\n## Presentations\n\n- *In-band OAM Overview*: http://www.slideshare.net/frankbrockners/nextgen-network-telemetry-is-within-your-packets-inband-oam\n\n- *Proof of transit*: Securely verifying a path or service chain: http://www.slideshare.net/frankbrockners/proof-of-transit-securely-verifying-a-path-or-service-chain\n\n## Blogs\n\n- What if you had a trip-recorder for all your traffic at line rate performance? http://blogs.cisco.com/getyourbuildon/a-trip-recorder-for-all-your-traffic\n- Verify my service chain! http://blogs.cisco.com/getyourbuildon/verify-my-service-chain \n\n## Demo videos on YouTube\n\nYoutube In-Band OAM channel: https://www.youtube.com/channel/UC0WJOAKBTrftyosP590RrXw \n\n## References\n\n\n\n - [draft-brockners-inband-oam-requirements]\n              Brockners, F., Bhandari, S., Dara, S., Pignataro, C.,\n              Gedler, H., Leddy, J., Youell, S., Mozes, D., Mizrahi, T.,\n              Lapukhov, P., Chang, R., \"Requirements\n              for inband OAM\", October 2016. (no longer maintained.\n              Draft served the purpose of fueling the discussion at IETF).\n\n - [draft-ietf-ippm-ioam-data]\n              Brockners, F., Bhandari, S., Dara, S., Pignataro, C.,\n              Gedler, H., Leddy, J., Youell, S., Mozes, D., Mizrahi, T.,\n              Lapukhov, P., Chang, R., \"Data Formats for in-situ\n              OAM\", July 2019.\n\n - [draft-ioametal-ippm-6man-ioam-ipv6-options]\n\t      S. Bhandari et al., \"In-situ OAM IPv6 Options\", March 2019.\n\n - [draft-ioametal-ippm-6man-ioam-ipv6-deployment]\n\t      S. Bhandari et al., \"Deployment Considerations for In-situ OAM with IPv6 Options\", March 2019.\n\n - [draft-ietf-sfc-ioam-nsh]\n              Brockners et al., \"NSH Encapsulation for In-situ OAM Data\",\n              March 2019.\n\n - [draft-brockners-ippm-ioam-vxlan-gpe]\n              Brockners et al., \"VXLAN-GPE Encapsulation for In-situ OAM Data\",\n              July 2019.\n\n - [draft-brockners-ippm-ioam-geneve]\n              Brockners et al., \"Geneve Encapsulation for In-situ OAM Data\",\n              March 2019.\n\n - [draft-weis-ippm-ioam-eth] \n              Weis et al., \"GRE Encapsulation for In-situ OAM Data\",\n              March 2019.\n\n - [draft-spiegel-ippm-ioam-rawexport]\n              Spiegel et al., \"In-situ OAM raw data export with IPFIX\",\n              July 2019.\n\n - [draft-brockners-inband-oam-transport]\n              Brockners, F., Bhandari, S., Dara, S., Pignataro, C.,\n              Gedler, H., Leddy, J., Youell, S., Mozes, D., Mizrahi, T.,\n              Lapukhov, P., Chang, R., \"Encapsulations for in-situ\n              OAM\", October 2016. (replaced by individual encapsulation\n              drafts - see above).\n\n - [draft-ietf-sfc-proof-of-transit]\n              Brockners, F., Bhandari, S., Dara, S., Pignataro, C.,\n              Gedler, H., Leddy, J., Youell, S., Mozes, D., Mizrahi, T.,\n              \"Proof of transit\", March 2019.\n\n - [SPUD]\n              Hildebrand, J. and B. Trammell, \"Substrate Protocol for\n              User Datagrams (SPUD) Prototype\", draft-hildebrand-spud-\n              prototype-03 (work in progress), March 2015.\n\n - [P4]       Kim, , \"P4: In-band Network Telemetry (INT)\", September\n              2015.\n\n - [I-D.lapukhov-dataplane-probe]\n              Lapukhov, P. and Chang R., \"Data-plane\n              probe for in-band telemetry collection\", draft-lapukhov-\n              dataplane-probe-02 (work in progress), June 2016.\n\n# Team:\n\nCurrent team:\n- Frank Brockners\n- Shwetha Bhandari\n- Srihari Raghavan\n- Vengada Prasad Govindan \n- Ananthakrishnan Rajamani\n- Akshaya Nadahalli\n- Carlos Pignataro\n\nFormer team members include:\n- Ranganathan T.S\n- Karthik Babu Harichandra Babu \n- Sagar Srivatsav\n- Manaswi G Reddy\n\n# Current Status\nIn development\n\n[draft-ioametal-ippm-6man-ioam-ipv6-options]:https://tools.ietf.org/html/draft-ioametal-ippm-6man-ioam-ipv6-options-02\n[draft-ioametal-ippm-6man-ioam-ipv6-deployment]:https://tools.ietf.org/html/draft-ioametal-ippm-6man-ioam-ipv6-deployment-01\n[draft-brockners-inband-oam-requirements]: https://tools.ietf.org/html/draft-brockners-inband-oam-requirements-03\n[draft-ietf-sfc-proof-of-transit]: https://tools.ietf.org/html/draft-ietf-sfc-proof-of-transit-02\n[draft-ietf-ippm-ioam-data]: https://tools.ietf.org/html/draft-ietf-ippm-ioam-data-02\n[draft-brockners-inband-oam-transport]: https://tools.ietf.org/html/draft-brockners-inband-oam-transport-05\n[draft-spiegel-ippm-ioam-rawexport]:https://www.ietf.org/id/draft-spiegel-ippm-ioam-rawexport-02.txt\n[draft-ietf-sfc-ioam-nsh]:https://tools.ietf.org/html/draft-ietf-sfc-ioam-nsh-01\n[draft-brockners-ippm-ioam-vxlan-gpe]:https://tools.ietf.org/html/draft-brockners-ippm-ioam-vxlan-gpe-00\n[draft-brockners-ippm-ioam-geneve]:https://tools.ietf.org/html/draft-brockners-ippm-ioam-geneve-00\n[draft-weis-ippm-ioam-eth]:https://tools.ietf.org/html/draft-weis-ippm-ioam-eth-01\n[p4]: http://p4.org/p4/inband-network-telemetry/\n[SPUD]: https://tools.ietf.org/html/draft-hildebrand-spud-prototype-03\n[fd.io]: http://fd.io\n[RFC0791]: https://tools.ietf.org/html/rfc0791.html\n[segment-routing]: https://tools.ietf.org/html/draft-ietf-spring-segment-routing-07\n[segment-routing-header]: https://tools.ietf.org/html/draft-ietf-6man-segment-routing-header-02\n[lisp-sr]: https://tools.ietf.org/html/draft-brockners-lisp-sr-02\n[VPP ioam configuration]: https://wiki.fd.io/view/VPP/Command-line_Interface_(CLI)_Guide#Inline_IPv6_OAM_Commands\n[I-D.lapukhov-dataplane-probe]: https://tools.ietf.org/html/draft-lapukhov-dataplane-probe-02\n[RFC7276]: https://tools.ietf.org/html/rfc7276\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fciscodevnet%2Fioam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fciscodevnet%2Fioam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fciscodevnet%2Fioam/lists"}