#!/usr/bin/env python3

import unittest

import scapy.compat
from scapy.packet import Raw
from scapy.layers.l2 import Ether, Dot1Q, GRE
from scapy.layers.inet import IP, UDP
from scapy.layers.inet6 import IPv6
from scapy.volatile import RandMAC, RandIP

from framework import tag_fixme_vpp_workers
from framework import VppTestCase, VppTestRunner
from vpp_sub_interface import L2_VTR_OP, VppDot1QSubint
from vpp_gre_interface import VppGreInterface
from vpp_teib import VppTeib
from vpp_ip import DpoProto
from vpp_ip_route import (
    VppIpRoute,
    VppRoutePath,
    VppIpTable,
    FibPathProto,
    VppMplsLabel,
)
from vpp_mpls_tunnel_interface import VppMPLSTunnelInterface
from util import ppp, ppc
from vpp_papi import VppEnum


@tag_fixme_vpp_workers
class TestGREInputNodes(VppTestCase):
    """GRE Input Nodes Test Case"""

    def setUp(self):
        super(TestGREInputNodes, self).setUp()

        # create 3 pg interfaces - set one in a non-default table.
        self.create_pg_interfaces(range(1))

        for i in self.pg_interfaces:
            i.admin_up()
            i.config_ip4()

    def tearDown(self):
        for i in self.pg_interfaces:
            i.unconfig_ip4()
            i.admin_down()
        super(TestGREInputNodes, self).tearDown()

    def test_gre_input_node(self):
        """GRE gre input nodes not registerd unless configured"""
        pkt = (
            Ether(dst=self.pg0.local_mac, src=self.pg0.remote_mac)
            / IP(src=self.pg0.remote_ip4, dst=self.pg0.local_ip4)
            / GRE()
        )

        self.pg0.add_stream(pkt)
        self.pg_start()
        # no tunnel created, gre-input not registered
        err = self.statistics.get_counter("/err/ip4-local/unknown_protocol")[0]
        self.assertEqual(err, 1)
        err_count = err

        # create gre tunnel
        gre_if = VppGreInterface(self, self.pg0.local_ip4, "1.1.1.2")
        gre_if.add_vpp_config()

        self.pg0.add_stream(pkt)
        self.pg_start()
        # tunnel created, gre-input registered
        err = self.statistics.get_counter("/err/ip4-local/unknown_protocol")[0]
        # expect no new errors
        self.assertEqual(err, err_count)


class TestGRE(VppTestCase):
    """GRE Test Case"""

    @classmethod
    def setUpClass(cls):
        super(TestGRE, cls).setUpClass()

    @classmethod
    def tearDownClass(cls):
        super(TestGRE, cls).tearDownClass()

    def setUp(self):
        super(TestGRE, self).setUp()

        # create 3 pg interfaces - set one in a non-default table.
        self.create_pg_interfaces(range(5))

        self.tbl = VppIpTable(self, 1)
        self.tbl.add_vpp_config()
        self.pg1.set_table_ip4(1)

        for i in self.pg_interfaces:
            i.admin_up()

        self.pg0.config_ip4()
        self.pg0.resolve_arp()
        self.pg1.config_ip4()
        self.pg1.resolve_arp()
        self.pg2.config_ip6()
        self.pg2.resolve_ndp()
        self.pg3.config_ip4()
        self.pg3.resolve_arp()
        self.pg4.config_ip4()
        self.pg4.resolve_arp()

    def tearDown(self):
        for i in self.pg_interfaces:
            i.unconfig_ip4()
            i.unconfig_ip6()
            i.admin_down()
        self.pg1.set_table_ip4(0)
        super(TestGRE, self).tearDown()

    def create_stream_ip4(self, src_if, src_ip, dst_ip, dscp=0, ecn=0):
        pkts = []
        tos = (dscp << 2) | ecn
        for i in range(0, 257):
            info = self.create_packet_info(src_if, src_if)
            payload = self.info_to_payload(info)
            p = (
                Ether(dst=src_if.local_mac, src=src_if.remote_mac)
                / IP(src=src_ip, dst=dst_ip, tos=tos)
                / UDP(sport=1234, dport=1234)
                / Raw(payload)
            )
            info.data = p.copy()
            pkts.append(p)
        return pkts

    def create_stream_ip6(self, src_if, src_ip, dst_ip, dscp=0, ecn=0):
        pkts = []
        tc = (dscp << 2) | ecn
        for i in range(0, 257):
            info = self.create_packet_info(src_if, src_if)
            payload = self.info_to_payload(info)
            p = (
                Ether(dst=src_if.local_mac, src=src_if.remote_mac)
                / IPv6(src=src_ip, dst=dst_ip, tc=tc)
                / UDP(sport=1234, dport=1234)
                / Raw(payload)
            )
            info.data = p.copy()
            pkts.append(p)
        return pkts

    def create_tunnel_stream_4o4(self, src_if, tunnel_src, tunnel_dst, src_ip, dst_ip):
        pkts = []
        for i in range(0, 257):
            info = self.create_packet_info(src_if, src_if)
            payload = self.info_to_payload(info)
            p = (
                Ether(dst=src_if.local_mac, src=src_if.remote_mac)
                / IP(src=tunnel_src, dst=tunnel_dst)
                / GRE()
                / IP(src=src_ip, dst=dst_ip)
                / UDP(sport=1234, dport=1234)
                / Raw(payload)
            )
            info.data = p.copy()
            pkts.append(p)
        return pkts

    def create_tunnel_stream_6o4(self, src_if, tunnel_src, tunnel_dst, src_ip, dst_ip):
        pkts = []
        for i in range(0, 257):
            info = self.create_packet_info(src_if, src_if)
            payload = self.info_to_payload(info)
            p = (
                Ether(dst=src_if.local_mac, src=src_if.remote_mac)
                / IP(src=tunnel_src, dst=tunnel_dst)
                / GRE()
                / IPv6(src=src_ip, dst=dst_ip)
                / UDP(sport=1234, dport=1234)
                / Raw(payload)
            )
            info.data = p.copy()
            pkts.append(p)
        return pkts

    def create_tunnel_stream_6o6(self, src_if, tunnel_src, tunnel_dst, src_ip, dst_ip):
        pkts = []
        for i in range(0, 257):
            info = self.create_packet_info(src_if, src_if)
            payload = self.info_to_payload(info)
            p = (
                Ether(dst=src_if.local_mac, src=src_if.remote_mac)
                / IPv6(src=tunnel_src, dst=tunnel_dst)
                / GRE()
                / IPv6(src=src_ip, dst=dst_ip)
                / UDP(sport=1234, dport=1234)
                / Raw(payload)
            )
            info.data = p.copy()
            pkts.append(p)
        return pkts

    def create_tunnel_stream_l2o4(self, src_if, tunnel_src, tunnel_dst):
        pkts = []
        for i in range(0, 257):
            info = self.create_packet_info(src_if, src_if)
            payload = self.info_to_payload(info)
            p = (
                Ether(dst=src_if.local_mac, src=src_if.remote_mac)
                / IP(src=tunnel_src, dst=tunnel_dst)
                / GRE()
                / Ether(dst=RandMAC("*:*:*:*:*:*"), src=RandMAC("*:*:*:*:*:*"))
                / IP(src=scapy.compat.raw(RandIP()), dst=scapy.compat.raw(RandIP()))
                / UDP(sport=1234, dport=1234)
                / Raw(payload)
            )
            info.data = p.copy()
            pkts.append(p)
        return pkts

    def create_tunnel_stream_vlano4(self, src_if, tunnel_src, tunnel_dst, vlan):
        pkts = []
        for i in range(0, 257):
            info = self.create_packet_info(src_if, src_if)
            payload = self.info_to_payload(info)
            p = (
                Ether(dst=src_if.local_mac, src=src_if.remote_mac)
                / IP(src=tunnel_src, dst=tunnel_dst)
                / GRE()
                / Ether(dst=RandMAC("*:*:*:*:*:*"), src=RandMAC("*:*:*:*:*:*"))
                / Dot1Q(vlan=vlan)
                / IP(src=scapy.compat.raw(RandIP()), dst=scapy.compat.raw(RandIP()))
                / UDP(sport=1234, dport=1234)
                / Raw(payload)
            )
            info.data = p.copy()
            pkts.append(p)
        return pkts

    def verify_tunneled_4o4(
        self, src_if, capture, sent, tunnel_src, tunnel_dst, dscp=0, ecn=0
    ):
        self.assertEqual(len(capture), len(sent))
        tos = (dscp << 2) | ecn

        for i in range(len(capture)):
            try:
                tx = sent[i]
                rx = capture[i]

                tx_ip = tx[IP]
                rx_ip = rx[IP]

                self.assertEqual(rx_ip.src, tunnel_src)
                self.assertEqual(rx_ip.dst, tunnel_dst)
                self.assertEqual(rx_ip.tos, tos)
                self.assertEqual(rx_ip.len, len(rx_ip))

                rx_gre = rx[GRE]
                rx_ip = rx_gre[IP]

                self.assertEqual(rx_ip.src, tx_ip.src)
                self.assertEqual(rx_ip.dst, tx_ip.dst)
                # IP processing post pop has decremented the TTL
                self.assertEqual(rx_ip.ttl + 1, tx_ip.ttl)

            except:
                self.logger.error(ppp("Rx:", rx))
                self.logger.error(ppp("Tx:", tx))
                raise

    def verify_tunneled_6o6(
        self, src_if, capture, sent, tunnel_src, tunnel_dst, dscp=0, ecn=0
    ):
        self.assertEqual(len(capture), len(sent))
        tc = (dscp << 2) | ecn

        for i in range(len(capture)):
            try:
                tx = sent[i]
                rx = capture[i]

                tx_ip = tx[IPv6]
                rx_ip = rx[IPv6]

                self.assertEqual(rx_ip.src, tunnel_src)
                self.assertEqual(rx_ip.dst, tunnel_dst)
                self.assertEqual(rx_ip.tc, tc)

                rx_gre = GRE(scapy.compat.raw(rx_ip[IPv6].payload))

                self.assertEqual(rx_ip.plen, len(rx_gre))

                rx_ip = rx_gre[IPv6]

                self.assertEqual(rx_ip.src, tx_ip.src)
                self.assertEqual(rx_ip.dst, tx_ip.dst)

            except:
                self.logger.error(ppp("Rx:", rx))
                self.logger.error(ppp("Tx:", tx))
                raise

    def verify_tunneled_4o6(self, src_if, capture, sent, tunnel_src, tunnel_dst):
        self.assertEqual(len(capture), len(sent))

        for i in range(len(capture)):
            try:
                tx = sent[i]
                rx = capture[i]

                rx_ip = rx[IPv6]

                self.assertEqual(rx_ip.src, tunnel_src)
                self.assertEqual(rx_ip.dst, tunnel_dst)

                rx_gre = GRE(scapy.compat.raw(rx_ip[IPv6].payload))

                self.assertEqual(rx_ip.plen, len(rx_gre))

                tx_ip = tx[IP]
                rx_ip = rx_gre[IP]

                self.assertEqual(rx_ip.src, tx_ip.src)
                self.assertEqual(rx_ip.dst, tx_ip.dst)

            except:
                self.logger.error(ppp("Rx:", rx))
                self.logger.error(ppp("Tx:", tx))
                raise

    def verify_tunneled_6o4(self, src_if, capture, sent, tunnel_src, tunnel_dst):
        self.assertEqual(len(capture), len(sent))

        for i in range(len(capture)):
            try:
                tx = sent[i]
                rx = capture[i]

                rx_ip = rx[IP]

                self.assertEqual(rx_ip.src, tunnel_src)
                self.assertEqual(rx_ip.dst, tunnel_dst)
                self.assertEqual(rx_ip.len, len(rx_ip))

                rx_gre = GRE(scapy.compat.raw(rx_ip[IP].payload))
                rx_ip = rx_gre[IPv6]
                tx_ip = tx[IPv6]

                self.assertEqual(rx_ip.src, tx_ip.src)
                self.assertEqual(rx_ip.dst, tx_ip.dst)

            except:
                self.logger.error(ppp("Rx:", rx))
                self.logger.error(ppp("Tx:", tx))
                raise

    def verify_tunneled_l2o4(self, src_if, capture, sent, tunnel_src, tunnel_dst):
        self.assertEqual(len(capture), len(sent))

        for i in range(len(capture)):
            try:
                tx = sent[i]
                rx = capture[i]

                tx_ip = tx[IP]
                rx_ip = rx[IP]

                self.assertEqual(rx_ip.src, tunnel_src)
                self.assertEqual(rx_ip.dst, tunnel_dst)
                self.assertEqual(rx_ip.len, len(rx_ip))

                rx_gre = rx[GRE]
                rx_l2 = rx_gre[Ether]
                rx_ip = rx_l2[IP]
                tx_gre = tx[GRE]
                tx_l2 = tx_gre[Ether]
                tx_ip = tx_l2[IP]

                self.assertEqual(rx_ip.src, tx_ip.src)
                self.assertEqual(rx_ip.dst, tx_ip.dst)
                # bridged, not L3 forwarded, so no TTL decrement
                self.assertEqual(rx_ip.ttl, tx_ip.ttl)

            except:
                self.logger.error(ppp("Rx:", rx))
                self.logger.error(ppp("Tx:", tx))
                raise

    def verify_tunneled_vlano4(
        self, src_if, capture, sent, tunnel_src, tunnel_dst, vlan
    ):
        try:
            self.assertEqual(len(capture), len(sent))
        except:
            ppc("Unexpected packets captured:", capture)
            raise

        for i in range(len(capture)):
            try:
                tx = sent[i]
                rx = capture[i]

                tx_ip = tx[IP]
                rx_ip = rx[IP]

                self.assertEqual(rx_ip.src, tunnel_src)
                self.assertEqual(rx_ip.dst, tunnel_dst)

                rx_gre = rx[GRE]
                rx_l2 = rx_gre[Ether]
                rx_vlan = rx_l2[Dot1Q]
                rx_ip = rx_l2[IP]

                self.assertEqual(rx_vlan.vlan, vlan)

                tx_gre = tx[GRE]
                tx_l2 = tx_gre[Ether]
                tx_ip = tx_l2[IP]

                self.assertEqual(rx_ip.src, tx_ip.src)
                self.assertEqual(rx_ip.dst, tx_ip.dst)
                # bridged, not L3 forwarded, so no TTL decrement
                self.assertEqual(rx_ip.ttl, tx_ip.ttl)

            except:
                self.logger.error(ppp("Rx:", rx))
                self.logger.error(ppp("Tx:", tx))
                raise

    def verify_decapped_4o4(self, src_if, capture, sent):
        self.assertEqual(len(capture), len(sent))

        for i in range(len(capture)):
            try:
                tx = sent[i]
                rx = capture[i]

                tx_ip = tx[IP]
                rx_ip = rx[IP]
                tx_gre = tx[GRE]
                tx_ip = tx_gre[IP]

                self.assertEqual(rx_ip.src, tx_ip.src)
                self.assertEqual(rx_ip.dst, tx_ip.dst)
                # IP processing post pop has decremented the TTL
                self.assertEqual(rx_ip.ttl + 1, tx_ip.ttl)

            except:
                self.logger.error(ppp("Rx:", rx))
                self.logger.error(ppp("Tx:", tx))
                raise

    def verify_decapped_6o4(self, src_if, capture, sent):
        self.assertEqual(len(capture), len(sent))

        for i in range(len(capture)):
            try:
                tx = sent[i]
                rx = capture[i]

                tx_ip = tx[IP]
                rx_ip = rx[IPv6]
                tx_gre = tx[GRE]
                tx_ip = tx_gre[IPv6]

                self.assertEqual(rx_ip.src, tx_ip.src)
                self.assertEqual(rx_ip.dst, tx_ip.dst)
                self.assertEqual(rx_ip.hlim + 1, tx_ip.hlim)

            except:
                self.logger.error(ppp("Rx:", rx))
                self.logger.error(ppp("Tx:", tx))
                raise

    def verify_decapped_6o6(self, src_if, capture, sent):
        self.assertEqual(len(capture), len(sent))

        for i in range(len(capture)):
            try:
                tx = sent[i]
                rx = capture[i]

                tx_ip = tx[IPv6]
                rx_ip = rx[IPv6]
                tx_gre = tx[GRE]
                tx_ip = tx_gre[IPv6]

                self.assertEqual(rx_ip.src, tx_ip.src)
                self.assertEqual(rx_ip.dst, tx_ip.dst)
                self.assertEqual(rx_ip.hlim + 1, tx_ip.hlim)

            except:
                self.logger.error(ppp("Rx:", rx))
                self.logger.error(ppp("Tx:", tx))
                raise

    def test_gre(self):
        """GRE IPv4 tunnel Tests"""

        #
        # Create an L3 GRE tunnel.
        #  - set it admin up
        #  - assign an IP Addres
        #  - Add a route via the tunnel
        #
        gre_if = VppGreInterface(self, self.pg0.local_ip4, "1.1.1.2")
        gre_if.add_vpp_config()

        #
        # The double create (create the same tunnel twice) should fail,
        # and we should still be able to use the original
        #
        try:
            gre_if.add_vpp_config()
        except Exception:
            pass
        else:
            self.fail("Double GRE tunnel add does not fail")

        gre_if.admin_up()
        gre_if.config_ip4()

        route_via_tun = VppIpRoute(
            self, "4.4.4.4", 32, [VppRoutePath("0.0.0.0", gre_if.sw_if_index)]
        )

        route_via_tun.add_vpp_config()

        #
        # Send a packet stream that is routed into the tunnel
        #  - they are all dropped since the tunnel's destintation IP
        #    is unresolved - or resolves via the default route - which
        #    which is a drop.
        #
        tx = self.create_stream_ip4(self.pg0, "5.5.5.5", "4.4.4.4")

        self.send_and_assert_no_replies(self.pg0, tx)

        #
        # Add a route that resolves<style>
@media only all and (prefers-color-scheme: dark) {
.highlight .hll { background-color: #49483e }
.highlight .c { color: #75715e } /* Comment */
.highlight .err { color: #960050; background-color: #1e0010 } /* Error */
.highlight .k { color: #66d9ef } /* Keyword */
.highlight .l { color: #ae81ff } /* Literal */
.highlight .n { color: #f8f8f2 } /* Name */
.highlight .o { color: #f92672 } /* Operator */
.highlight .p { color: #f8f8f2 } /* Punctuation */
.highlight .ch { color: #75715e } /* Comment.Hashbang */
.highlight .cm { color: #75715e } /* Comment.Multiline */
.highlight .cp { color: #75715e } /* Comment.Preproc */
.highlight .cpf { color: #75715e } /* Comment.PreprocFile */
.highlight .c1 { color: #75715e } /* Comment.Single */
.highlight .cs { color: #75715e } /* Comment.Special */
.highlight .gd { color: #f92672 } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .gi { color: #a6e22e } /* Generic.Inserted */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #75715e } /* Generic.Subheading */
.highlight .kc { color: #66d9ef } /* Keyword.Constant */
.highlight .kd { color: #66d9ef } /* Keyword.Declaration */
.highlight .kn { color: #f92672 } /* Keyword.Namespace */
.highlight .kp { color: #66d9ef } /* Keyword.Pseudo */
.highlight .kr { color: #66d9ef } /* Keyword.Reserved */
.highlight .kt { color: #66d9ef } /* Keyword.Type */
.highlight .ld { color: #e6db74 } /* Literal.Date */
.highlight .m { color: #ae81ff } /* Literal.Number */
.highlight .s { color: #e6db74 } /* Literal.String */
.highlight .na { color: #a6e22e } /* Name.Attribute */
.highlight .nb { color: #f8f8f2 } /* Name.Builtin */
.highlight .nc { color: #a6e22e } /* Name.Class */
.highlight .no { color: #66d9ef } /* Name.Constant */
.highlight .nd { color: #a6e22e } /* Name.Decorator */
.highlight .ni { color: #f8f8f2 } /* Name.Entity */
.highlight .ne { color: #a6e22e } /* Name.Exception */
.highlight .nf { color: #a6e22e } /* Name.Function */
.highlight .nl { color: #f8f8f2 } /* Name.Label */
.highlight .nn { color: #f8f8f2 } /* Name.Namespace */
.highlight .nx { color: #a6e22e } /* Name.Other */
.highlight .py { color: #f8f8f2 } /* Name.Property */
.highlight .nt { color: #f92672 } /* Name.Tag */
.highlight .nv { color: #f8f8f2 } /* Name.Variable */
.highlight .ow { color: #f92672 } /* Operator.Word */
.highlight .w { color: #f8f8f2 } /* Text.Whitespace */
.highlight .mb { color: #ae81ff } /* Literal.Number.Bin */
.highlight .mf { color: #ae81ff } /* Literal.Number.Float */
.highlight .mh { color: #ae81ff } /* Literal.Number.Hex */
.highlight .mi { color: #ae81ff } /* Literal.Number.Integer */
.highlight .mo { color: #ae81ff } /* Literal.Number.Oct */
.highlight .sa { color: #e6db74 } /* Literal.String.Affix */
.highlight .sb { color: #e6db74 } /* Literal.String.Backtick */
.highlight .sc { color: #e6db74 } /* Literal.String.Char */
.highlight .dl { color: #e6db74 } /* Literal.String.Delimiter */
.highlight .sd { color: #e6db74 } /* Literal.String.Doc */
.highlight .s2 { color: #e6db74 } /* Literal.String.Double */
.highlight .se { color: #ae81ff } /* Literal.String.Escape */
.highlight .sh { color: #e6db74 } /* Literal.String.Heredoc */
.highlight .si { color: #e6db74 } /* Literal.String.Interpol */
.highlight .sx { color: #e6db74 } /* Literal.String.Other */
.highlight .sr { color: #e6db74 } /* Literal.String.Regex */
.highlight .s1 { color: #e6db74 } /* Literal.String.Single */
.highlight .ss { color: #e6db74 } /* Literal.String.Symbol */
.highlight .bp { color: #f8f8f2 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #a6e22e } /* Name.Function.Magic */
.highlight .vc { color: #f8f8f2 } /* Name.Variable.Class */
.highlight .vg { color: #f8f8f2 } /* Name.Variable.Global */
.highlight .vi { color: #f8f8f2 } /* Name.Variable.Instance */
.highlight .vm { color: #f8f8f2 } /* Name.Variable.Magic */
.highlight .il { color: #ae81ff } /* Literal.Number.Integer.Long */
}
@media (prefers-color-scheme: light) {
.highlight .hll { background-color: #ffffcc }
.highlight .c { color: #888888 } /* Comment */
.highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */
.highlight .k { color: #008800; font-weight: bold } /* Keyword */
.highlight .ch { color: #888888 } /* Comment.Hashbang */
.highlight .cm { color: #888888 } /* Comment.Multiline */
.highlight .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
.highlight .cpf { color: #888888 } /* Comment.PreprocFile */
.highlight .c1 { color: #888888 } /* Comment.Single */
.highlight .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
.highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .gr { color: #aa0000 } /* Generic.Error */
.highlight .gh { color: #333333 } /* Generic.Heading */
.highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.highlight .go { color: #888888 } /* Generic.Output */
.highlight .gp { color: #555555 } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #666666 } /* Generic.Subheading */
.highlight .gt { color: #aa0000 } /* Generic.Traceback */
.highlight .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #008800; font-weight: bold } /* Keyword.Namespace */
.highlight .kp { color: #008800 } /* Keyword.Pseudo */
.highlight .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #888888; font-weight: bold } /* Keyword.Type */
.highlight .m { color: #0000DD; font-weight: bold } /* Literal.Number */
.highlight .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */
.highlight .na { color: #336699 } /* Name.Attribute */
.highlight .nb { color: #003388 } /* Name.Builtin */
.highlight .nc { color: #bb0066; font-weight: bold } /* Name.Class */
.highlight .no { color: #003366; font-weight: bold } /* Name.Constant */
.highlight .nd { color: #555555 } /* Name.Decorator */
.highlight .ne { color: #bb0066; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #0066bb; font-weight: bold } /* Name.Function */
.highlight .nl { color: #336699; font-style: italic } /* Name.Label */
.highlight .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */
.highlight .py { color: #336699; font-weight: bold } /* Name.Property */
.highlight .nt { color: #bb0066; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #336699 } /* Name.Variable */
.highlight .ow { color: #008800 } /* Operator.Word */
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
.highlight .mb { color: #0000DD; font-weight: bold } /* Literal.Number.Bin */
.highlight .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */
.highlight .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */
.highlight .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */
.highlight .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */
.highlight .sa { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Affix */
.highlight .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */
.highlight .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */
.highlight .dl { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Delimiter */
.highlight .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */
.highlight .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */
.highlight .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */
.highlight .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */
.highlight .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */
.highlight .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */
.highlight .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */
.highlight .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */
.highlight .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */
.highlight .bp { color: #003388 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #0066bb; font-weight: bold } /* Name.Function.Magic */
.highlight .vc { color: #336699 } /* Name.Variable.Class */
.highlight .vg { color: #dd7700 } /* Name.Variable.Global */
.highlight .vi { color: #3333bb } /* Name.Variable.Instance */
.highlight .vm { color: #336699 } /* Name.Variable.Magic */
.highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */
}
</style><div class="highlight"><pre><span></span><span class="gh">#</span> BFD module    {#bfd_doc}

<span class="gu">##</span> Overview

Bidirectional Forwarding Detection in VPP currently supports single-hop UDP
transport based on RFC 5880 and RFC 5881.

<span class="gu">##</span> Usage

<span class="gu">###</span> General usage

BFD sessions are created using APIs only. The following CLIs are implemented,
which call the APIs to manipulate the BFD:

<span class="gu">####</span> Show commands:

<span class="k">&gt; </span><span class="ge">show bfd [keys|sessions|echo-source]</span>

Show the existing keys, sessions or echo-source.

<span class="gu">####</span> Key manipulation

<span class="gu">#####</span> Create a new key or modify an existing key

<span class="k">&gt; </span><span class="ge">bfd key set conf-key-id &lt;id&gt; type &lt;keyed-sha1|meticulous-keyed-sha1&gt; secret &lt;secret&gt;</span>

Parameters:

<span class="k">*</span> conf-key-id     - local configuration key ID, used to uniquely identify this key
<span class="k">*</span> type            - type of the key
<span class="k">*</span> secret          - shared secret (hex data)

Example:

<span class="k">&gt; </span><span class="ge">bfd key set conf-key-id 2368880803 type meticulous-keyed-sha1 secret 69d685b0d990cdba46872706dc</span>

Notes:

<span class="k">*</span> in-use key cannot be modified

<span class="gu">#####</span> Delete an existing key

<span class="k">&gt; </span><span class="ge">bfd key del conf-key-id &lt;id&gt;</span>

Parameters:

<span class="k">*</span> conf-key-id     - local configuration key ID, used to uniquely identify this key

Example:

<span class="k">&gt; </span><span class="ge">bfd key del conf-key-id 2368880803</span>

Notes:

<span class="k">*</span>  in-use key cannot be deleted

<span class="gu">#####</span> Create a new (plain or authenticated) BFD session

<span class="k">&gt; </span><span class="ge">bfd udp session add interface &lt;interface&gt; local-addr &lt;address&gt; peer-addr &lt;address&gt; desired-min-tx &lt;interval&gt; required-min-rx &lt;interval&gt; detect-mult &lt;multiplier&gt; [ conf-key-id &lt;ID&gt; bfd-key-id &lt;ID&gt; ]</span>

Parameters:

<span class="k">*</span> interface       - interface to which this session is tied to
<span class="k">*</span> local-addr      - local address (ipv4 or ipv6)
<span class="k">*</span> peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
<span class="k">*</span> desired-min-tx  - desired minimum tx interval (microseconds)
<span class="k">*</span> required-min-rx - required minimum rx interval (microseconds)
<span class="k">*</span> detect-mult     - detect multiplier (must be non-zero)
<span class="k">*</span> conf-key-id     - local configuration key ID
<span class="k">*</span> bfd-key-id      - BFD key ID, as carried in BFD control frames

Example:

<span class="k">&gt; </span><span class="ge">bfd udp session add interface pg0 local-addr fd01:1::1 peer-addr fd01:1::2 desired-min-tx 100000 required-min-rx 100000 detect-mult 3 conf-key-id 1029559112 bfd-key-id 13</span>

Notes:

<span class="k">*</span> if conf-key-id and bfd-key-id are not specified, session is non-authenticated
<span class="k">*</span> desired-min-tx controls desired transmission rate of both control frames and echo packets

<span class="gu">#####</span> Modify BFD session

<span class="k">&gt; </span><span class="ge">bfd udp session mod interface &lt;interface&gt; local-addr &lt;address&gt; peer-addr &lt;address&gt; desired-min-tx &lt;interval&gt; required-min-rx &lt;interval&gt; detect-mult &lt;multiplier&gt;</span>

Parameters:

<span class="k">*</span> interface       - interface to which this session is tied to
<span class="k">*</span> local-addr      - local address (ipv4 or ipv6)
<span class="k">*</span> peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
<span class="k">*</span> desired-min-tx  - desired minimum tx interval (microseconds)
<span class="k">*</span> required-min-rx - required minimum rx interval (microseconds)
<span class="k">*</span> detect-mult     - detect multiplier (must be non-zero)

Example:

<span class="k">&gt; </span><span class="ge">bfd udp session mod interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2 desired-min-tx 300000 required-min-rx 200000 detect-mult 12</span>

Notes:

<span class="k">*</span> desired-min-tx controls desired transmission rate of both control frames and echo packets

<span class="gu">#####</span> Delete an existing BFD session

<span class="k">&gt; </span><span class="ge">bfd udp session del interface &lt;interface&gt; local-addr &lt;address&gt; peer-addr&lt;address&gt;</span>

Parameters:

<span class="k">*</span> interface       - interface to which this session is tied to
<span class="k">*</span> local-addr      - local address (ipv4 or ipv6)
<span class="k">*</span> peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)

Example:

<span class="k">&gt; </span><span class="ge">bfd udp session del interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2</span>

<span class="gu">#####</span> Set session admin-up or admin-down

<span class="k">&gt; </span><span class="ge">bfd udp session set-flags interface &lt;interface&gt; local-addr &lt;address&gt; peer-addr &lt;address&gt; admin &lt;up|down&gt;</span>

Parameters:

<span class="k">*</span> interface       - interface to which this session is tied to
<span class="k">*</span> local-addr      - local address (ipv4 or ipv6)
<span class="k">*</span> peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
<span class="k">*</span> admin           - up/down based on desired action

Example:

<span class="k">&gt; </span><span class="ge">bfd udp session set-flags admin down interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2</span>

<span class="gu">#####</span> Activate/change authentication for existing session

<span class="k">&gt; </span><span class="ge">bfd udp session auth activate interface &lt;interface&gt; local-addr &lt;address&gt; peer-addr &lt;address&gt; conf-key-id &lt;ID&gt; bfd-key-id &lt;ID&gt; [ delayed &lt;yes|no&gt; ]</span>

Parameters:

<span class="k">*</span> interface       - interface to which this session is tied to
<span class="k">*</span> local-addr      - local address (ipv4 or ipv6)
<span class="k">*</span> peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
<span class="k">*</span> conf-key-id     - local configuration key ID
<span class="k">*</span> bfd-key-id      - BFD key ID, as carried in BFD control frames
<span class="k">*</span> delayed         - is yes then this action is delayed until the peer performs the same action

Example:

<span class="k">&gt; </span><span class="ge">bfd udp session auth activate interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2 conf-key-id 540928695 bfd-key-id 239 delayed yes</span>

Notes:

<span class="k">*</span> see [Delayed option] for more information

<span class="gu">#####</span> Deactivate authentication for existing session

<span class="k">&gt; </span><span class="ge">bfd udp session auth deactivate interface &lt;interface&gt; local-addr &lt;address&gt; peer-addr &lt;address&gt; [ delayed &lt;yes|no&gt; ]</span>

Parameters:

<span class="k">*</span> interface       - interface to which this session is tied to
<span class="k">*</span> local-addr      - local address (ipv4 or ipv6)
<span class="k">*</span> peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
<span class="k">*</span> delayed         - is yes then this action is delayed until the peer performs the same action

Example:

<span class="k">&gt; </span><span class="ge">bfd udp session auth deactivate interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2</span>

Notes:

<span class="k">*</span> see [Delayed option] for more information

<span class="gu">#####</span> Set echo-source interface

<span class="k">&gt; </span><span class="ge">bfd udp echo-source set interface &lt;interface&gt;</span>

Parameters:

<span class="k">*</span> interface       - interface used for getting source address for echo packets

Example:

<span class="k">&gt; </span><span class="ge">bfd udp echo-source set interface loop0</span>

<span class="gu">#####</span> Delete echo-source interface

<span class="k">&gt; </span><span class="ge">bfd udp echo-source del</span>

Example:

<span class="k">&gt; </span><span class="ge">bfd udp echo-source del</span>

<span class="gu">###</span> Authentication

BFD sessions should be authenticated for security purposes. SHA1 and meticulous
SHA1 authentication is supported by VPP. First, authentication keys are
configured in VPP and afterwards they can be used by sessions.

There are two key IDs in the scope of BFD session:

<span class="k">*</span> configuration key ID is the internal unique key ID inside VPP and is never
  communicated to any peer, it serves only the purpose of identifying the key
<span class="ge">* BFD key ID is the key ID carried in BFD control frames and is used for</span>
<span class="ge">  verifying authentication</span>

<span class="ge">#### Turning auth on/off</span>

<span class="ge">Authentication can be turned on or off at any time. Care must be taken however,</span>
<span class="ge">to either synchronize the authentication manipulation with peer&#39;s actions</span>
<span class="ge">to avoid the session going down.</span>

<span class="ge">##### Delayed option</span>

<span class="ge">Delayed option is useful for synchronizing authentication changes with a peer.</span>
<span class="ge">If it&#39;s specified, then authentication change is not performed immediately.</span>
<span class="ge">In this case, VPP continues to transmit packets using the old authentication</span>
<span class="ge">method (unauthenticated or using old sha1 key). If a packet is received, which</span>
<span class="ge">does not pass the current authentication, then VPP tries to authenticate it</span>
<span class="ge">using the new method (which might be none, if deactivating authentication)</span>
<span class="ge">and if it passes, then the new authentication method is put in use.</span>

<span class="ge">The recommended procedure for enabling/changing/disabling session </span>
<span class="ge">authentication is:</span>

<span class="ge">1. perform authentication change on vpp&#39;s side with delayed option set to yes</span>
<span class="ge">2. perform authentication change on peer&#39;s side (without delayed option)</span>

<span class="ge">Notes:</span>

<span class="ge">*</span> if both peers use delayed option at the same time, the change will never
  be carried out, since none of the peers will see any packet with the new
  authentication which could trigger the change
<span class="k">*</span> remote peer does not need to support or even be aware of this mechanism
  for it to work properly


<span class="gu">###</span> Echo function

Echo function is used by VPP whenever a peer declares the willingness
to support it, echo-source is set and it contains a usable subnet (see below).
When echo function is switched on, the required min rx interval advertised
to peer is set to 1 second (or the configured value, if its higher).

<span class="gu">####</span> Echo source address

Because echo packets are only looped back (and not processed in any way)
by a peer, it&#39;s necessary to set the source address in a way which avoids
packet drop due to spoofing protection by VPP. Per RFC, the source address
should not be in the subnet set on the interface over which the echo packets
are sent. Also, it must not be any VPP-local address, otherwise the packet
gets dropped on receipt by VPP. The solution is to create a loopback interface
with a (private) IPv4/IPv6 subnet assigned as echo-source. The BFD then picks
an unused address from the subnet by flipping the last bit and uses that as
source address in the echo packets, thus meeting RFC recommendation while
avoiding spoofing protection.

Example: if 10.10.10.3/31 is the subnet, then 10.10.10.2 will be used as
         source address in (IPv4) echo packets

<span class="gu">###</span> Demand mode

Demand mode is respected by VPP, but not used locally. The only scenario when
demand mode could make sense currently is when echo is active. Because echo
packets are inherently insecure against an adversary looping them back a poll
sequence would be required for slow periodic connectivity verification anyway.
It&#39;s more efficient to just ask the remote peer to send slow periodic control
frames without VPP initiating periodic poll sequences.

<span class="gu">###</span> Admin-down

Session may be put admin-down at any time. This immediately causes the state
to be changed to AdminDown and remain so unless the session is put admin-up.

<span class="gu">##</span> BFD implementation notes

Because BFD can work over different transport layers, the BFD code is separated
into core BFD functionality - main module implemented in bfd_main.c
and transport-specific code implemented in bfd_udp.c.

<span class="gu">###</span> Main module

Main module is responsible for handling all the BFD functionality defined
in RFC 5880.

<span class="gu">####</span> Internal API

Internal APIs defined in bfd_main.h are called from transport-specific code
to create/modify/delete

<span class="gu">####</span> Packet receipt

When a packet is received by the transport layer, it is forwarded to main
module (to main thread) via an RPC call. At this point, the authentication has
been verified, so the packet is consumed, session parameters are updated
accordingly and state change (if applicable). Based on these, the timeouts
are adjusted if required and an event is sent to the process node to wake up
and recalculate sleep time.

<span class="gu">####</span> Packet transmit

Main module allocates a vlib_buffer_t, creates the required BFD frame (control
or echo in it), then calls the transport layer to add the transport layer.
Then a frame containing the buffer to the aprropriate node is created
and enqueued.

<span class="gu">####</span> Process node

Main module implements one process node which is a simple loop. The process
node gets next timeout from the timer wheel, sleeps until the timeout expires
and then calls a timeout routine which drives the state machine for each
session which timed out. The sleep is interrupted externally via vlib event,
when a session is added or modified in a way which might require timer wheel
manipulation. In this case the caller inserts the necessary timeout to timer
wheel and then signals the process node to wake up early, handle possible
timeouts and recalculate the sleep time again.

<span class="gu">####</span> State machine

Default state of BFD session when created is Down, per RFC 5880. State changes
to Init, Up or Down based on events like received state from peer and timeouts.
The session state can be set AdminDown using a binary API, which prevents it
from going to any other state, until this limitation is removed. This state
is advertised to peers in slow periodic control frames.

For each session, the following timeouts are maintained:

<span class="k">1.</span> tx timeout - used for sending out control frames
<span class="k">2.</span> rx timeout - used for detecting session timeout
<span class="k">3.</span> echo tx timeout - used for sending out echo frames
<span class="k">3.</span> echo rx timeout - used for detecting session timeout based on echo

These timeouts are maintained in cpu clocks and recalculated when appropriate
(e.g. rx timeout is bumped when a packet is received, keeping the session
alive). Only the earliest timeout is inserted into the timer wheel at a time
and timer wheel events are never deleted, rather spurious events are ignored.
This allows efficient operation, like not inserting events into timing wheel
for each packet received or ignoring left-over events in case a bfd session
gets removed and a new one is recreated with the same session index.

<span class="gu">####</span> Authentication keys management

Authentication keys are managed internally in a pool, with each key tracking
it&#39;s use count. The removal/modification is only allowed if the key is not in
use.

<span class="gu">###</span> UDP module

UDP module is responsible for:

<span class="k">1.</span> public APIs/CLIs to configure BFD over UDP.
<span class="k">2.</span> support code cal