diff options
Diffstat (limited to 'src/plugins/ioam/ioam_udppinger_doc.md')
-rw-r--r-- | src/plugins/ioam/ioam_udppinger_doc.md | 191 |
1 files changed, 191 insertions, 0 deletions
diff --git a/src/plugins/ioam/ioam_udppinger_doc.md b/src/plugins/ioam/ioam_udppinger_doc.md new file mode 100644 index 00000000000..3bb42b7f290 --- /dev/null +++ b/src/plugins/ioam/ioam_udppinger_doc.md @@ -0,0 +1,191 @@ +## UDP-Pinger for IPv6 with IOAM {#ioam_udppinger_doc} + +Traditionally to detect and isolate network faults, ping and traceroute +are used. But in a complex network with large number of U/E-CMP being +availble, it would be difficult to detect and isolate faults in the +network. Also detecting loss/reordering/duplication of packets becomes +much harder. [draft-lapukhov-dataplane-probe] uses active probes to +solve the above mentioned problems. UDP-Pinger with IOAM, would combine +[draft-lapukhov-dataplane-probe] with [IOAM-ietf-data] and +[IOAM-ietf-transport] to provide a more sophisticated way for +detection/isolation of network faults and enable network telemetry. + +UDP-Pinger for IPv6 does: +- Crafts and sends Probe packets from source node to destination. +- Probe packet is an IPv6 packet with HBH header to collect IOAM data +and UDP header followed by payload. +- UDP source and destination ports are varied to cover all possible +paths in network as well as to simulate real application traffic. +- IOAM Trace option is used to record the path Probe packets take +and also for measuring latency. +- IOAM E2E option is used to measure packet loss, reordering and +duplicate packets. +- UDP payload follows packet format in [draft-lapukhov-dataplane-probe] +and is used on source/destination nodes to identify Probe/Reply packets. +- Destination node on receiving Probe packet sends a reply back to source. + Reply packet is formed by exchanging source and destination IP addresses +and packet type in UDP payload. +- Source node on receiving Reply packet can trace packet Path and measure +latency, packet loss, reordering, duplication. +- On detecting fault in network, Probe packets are sent with loopback +flag set. On seeing loopback flag, each device in network along with +forwarding the packet, also sends a copy back to source. With this +Source node can corelate and detect the faulty node/link. + +## Configuration +Following section describes how to enable UDP-Pinger on a VPP node. +Please note that IOAM configurations as mentioned in @subpage ioam_ipv6_doc +have to be made prior to starting any of the below configurations. + +### UDP-Pinger Enable/Disable +For configuring UDP-Pinger between two end-points, following parametrs +need to be provided by using the CLI: + + set udp-ping src <local IPv6 address> src-port-range <local port range> + dst <remote IPv6 address> dst-port-range <destination port range> + interval <time interval in sec> [fault-detect] [disable] + +- src : IPv6 address of local node. +- src-port-range : Port range for source port in UDP header. + Syntax is <start_port>:<end_port> +- dst : IPv6 address of the destination node. +- dst-port-range : Port range for destination port in UDP header. + Syntax is <start_port>:<end_port> +- interval : Time interval in seconds for which Probe packets need to + be sent out. +- fault-detect : This is to enable IOAM loopback functionality on + detecting a failure and to detect faulty node/link. +- disable : Used for deleting a UDP-Ping flow. + +Example: + + To create a UDP-Pinger session: + set udp-ping src db00::1 src-port-range 5000:5002 dst db02::1 dst-port-range 6000:6002 interval 1 fault-detect + + To delete a UDP-Pinger session: + set udp-ping src db00::1 src-port-range 5000:5002 dst db02::1 dst-port-range 6000:6002 interval 1 fault-detect disable + +### UDP-Pinger Data Export +For exporting network telemetry data extracted from UDP-Pinger sessions, +below command is used. Data is exported as IP-Fix records. + + set udp-ping export-ipfix [disable] + + On enabling udp-ping export, UDP-Pinger data is exported as + IP-Fix record to IP-Fix collector address as configured in + IP-Fix using the command: + + set ipfix exporter collector <Remote IP Address> src <Local IP address> + +Following data is exported from UDP-Pinger: +- IOAM Trace information for each of UDP-Pinger flow +- Roundtrip Delay +- Packet loss count +- Reordered Packet count +- Duplicate Packet count + +Example: + + To enable export: + set ipfix exporter collector 172.16.1.254 src 172.16.1.229 + set udp-ping export-ipfix + + To disable export: + set udp-ping export-ipfix disable + +## Operational data +For checking the state of the UDP-Pinger sessions, below command can be used: + + show udp-ping summary + +Command displays follwing for each UDP-Pinger session: +- IOAM Trace information for each of UDP-Pinger flow +- Roundtrip Delay +- Packet loss count +- Reordered Packet count +- Duplicate Packet count + +Example: + + vpp#show udp-ping summary + UDP-Ping data: + Src: db00::1, Dst: db02::1 + Start src port: 5000, End src port: 5002 + Start dst port: 6000, End dst port: 6002 + Interval: 1 + + Src Port - 5000, Dst Port - 6000, Flow CTX - 0 + Path State - Up + Path Data: + pkt_sent : 400 + pkt_counter : 400 + bytes_counter : 458700 + Trace data: + pkt_sent : 400 + pkt_counter : 400 + bytes_counter : 45870 + Trace data: + path_map: + + node_id: 0x1, ingress_if: 1, egress_if: 2, state:UP + node_id: 0x2, ingress_if: 0, egress_if: 2, state:UP + node_id: 0x3, ingress_if: 3, egress_if: 0, state:UP + node_id: 0x2, ingress_if: 4, egress_if: 9, state:UP + node_id: 0x1, ingress_if: 10, egress_if: 0, state:UP + pkt_counter: 400 + bytes_counter: 45870 + min_delay: 10 + max_delay: 50 + mean_delay: 15 + + POT data: + sfc_validated_count : 0 + sfc_invalidated_count : 0 + + Seqno Data: + RX Packets : 400 + Lost Packets : 0 + Duplicate Packets : 0 + Reordered Packets : 0 + + Src Port - 5000, Dst Port - 6001, Flow CTX - 1 + Path State - Down + Path Data: + pkt_sent : 500 + pkt_counter : 400 + bytes_counter : 45870 + Trace data: + pkt_sent : 500 + pkt_counter : 400 + bytes_counter : 45870 + Trace data: + path_map: + + node_id: 0x1, ingress_if: 1, egress_if: 2, state:UP + node_id: 0x2, ingress_if: 0, egress_if: 2, state:UP + node_id: 0x3, ingress_if: 3, egress_if: 0, state:Down + node_id: 0x2, ingress_if: 4, egress_if: 9, state:Down + node_id: 0x1, ingress_if: 10, egress_if: 0, state:Down + pkt_counter: 500 + bytes_counter: 45870 + min_delay: 50 + max_delay: 500 + mean_delay: 100 + + POT data: + sfc_validated_count : 0 + sfc_invalidated_count : 0 + + Seqno Data: + RX Packets : 400 + Lost Packets : 100 + Duplicate Packets : 20 + Reordered Packets : 5 + + <So on for other source/destination port combination> + + +[draft-lapukhov-dataplane-probe]:<https://tools.ietf.org/html/draft-lapukhov-dataplane-probe-01> +[IOAM-ietf-data]:<https://tools.ietf.org/html/draft-brockners-inband-oam-data-04> +[IOAM-ietf-transport]:<https://tools.ietf.org/html/draft-brockners-inband-oam-transport-03> + |