src/plugins/srv6-am/am_plugin_doc.md

   1 # SRv6 endpoint to SR-unaware appliance via masquerading (End.AM) {#srv6_am_plugin_doc}
   2
   3 ## Overview
   4
   5 The "Endpoint to SR-unaware appliance via masquerading" (End.AM) is a two-parts
   6 function for processing SRv6 **inserted** traffic on behalf of an SR-unaware
   7 appliance. The first part decrements the Segments Left value and **replaces the
   8 IPv6 Destination Address with the last segment in the SRH**, while the second
   9 restores the IPv6 Destination Address with the active segment in the traffic
  10 coming back from the appliance.
  11
  12 In this scenario, we assume that the appliance can only inspect, drop or perform
  13 limited changes to the packets. In particular, the appliance must not change the
  14 IP Destination Address of the packet, terminate a transport connection nor
  15 generate arbitrary packets. For example, Firewalls, Intrusion Detection Systems,
  16 Deep Packet Inspectors are among the appliances that can be supported in this
  17 scenario.
  18
  19 ## Pseudo-code
  20
  21 When instantiating an End.AM SID, the following parameters are required:
  22
  23 - APP-ADDR: IP or Ethernet address of the appliance
  24 - IFACE-OUT: local interface for sending traffic towards the appliance
  25 - IFACE-IN: local interface receiving the traffic coming back from the appliance
  26
  27 Packets can be sent to and received from an appliance on the same interface
  28 (IFACE-IN = IFACE-OUT).
  29
  30 ### Masquerading
  31
  32 Upon receiving a packet destined to S, where S is a local End.AM SID, a node N
  33 does:
  34
  35         IF NH=SRH & SL > 0 THEN                                         ;; Ref1
  36                 Decrement SL
  37                 Write the last SID in the DA
  38                 Forward the packet on IFACE-OUT
  39         ELSE
  40                 Drop the packet
  41
  42 **Ref1:** an End.AM must not be the last SID.
  43
  44 ### De-masquerading
  45
  46 Upon receiving a non-link-local IPv6 packet on IFACE-IN, a node N does:
  47
  48         IF NH=SRH THEN
  49                 Replace IP DA with SRH[SL]
  50                 Lookup DA in the appropriate table and proceed accordingly
  51
  52 De-masquerading is a policy attached to IFACE-IN that intercepts all packets
  53 coming back from the appliance and restores the destination address.  This
  54 occurs before any lookup on the packet destination address (e.g. in "My Local
  55 SIDs" table or in the FIB) is performed.
  56
  57 ## Benefits
  58
  59 The End.AM masquerading function brings the following benefits:
  60
  61 1. The appliance receives a packet with the source and destination addresses
  62 respectively set as the original source and the final destination.
  63 2. The appliance does not try and inspect the SRH, as RFC2460 specifies that
  64 routing extension headers are not examined or processed by transit nodes.
  65
  66 ## Limitations
  67
  68 An End.AM SID may be present in any number of segment lists at the same time.
  69
  70 However, since the returning traffic from the appliance is processed based on
  71 the receiving interface (IFACE-IN), this interface may only be bound to a single
  72 End.AM SID at a time.
  73
  74 In the case of a bi-directional service chain, the same End.AM SID and receiving
  75 interface (IFACE-IN) may be used in both directions.
  76
  77 ## Configuration
  78
  79 The following CLI instantiates a new End.AM segment that sends masqueraded
  80 traffic on interface `IFACE-OUT` towards an appliance at address `APP-ADDR` and
  81 restores the active segment in the IPv6 header of the packets coming back on
  82 interface `IFACE-IN`.
  83
  84         sr localsid address SID behavior end.am nh APP-ADDR oif IFACE-OUT iif IFACE-IN
  85
  86 For example, the following command configures the SID `1::A1` with an End.AM
  87 function for sending traffic on interface `GigabitEthernet0/8/0` to the appliance at
  88 address `A1::`, and receiving it back on interface `GigabitEthernet0/9/0`.
  89
  90         sr localsid address 1::A1 behavior end.am nh A1:: oif GigabitEthernet0/8/0 iif GigabitEthernet0/9/0
  91