diff options
Diffstat (limited to 'src/plugins')
| -rw-r--r-- | src/plugins/srv6-ad/ad_plugin_doc.md | 88 | ||||
| -rw-r--r-- | src/plugins/srv6-am/am_plugin_doc.md | 161 | ||||
| -rw-r--r-- | src/plugins/srv6-as/as_plugin_doc.md | 199 |
3 files changed, 247 insertions, 201 deletions
diff --git a/src/plugins/srv6-ad/ad_plugin_doc.md b/src/plugins/srv6-ad/ad_plugin_doc.md index fc8ebfe352f..993eeb63589 100644 --- a/src/plugins/srv6-ad/ad_plugin_doc.md +++ b/src/plugins/srv6-ad/ad_plugin_doc.md @@ -2,22 +2,72 @@ ## Overview -The "Endpoint to SR-unaware appliance via dynamic proxy" (End.AD) is a two-parts -proxy function for processing SRv6 encapsulated traffic on behalf of an -SR-unaware appliance. The first part decapsulates the incoming traffic and sends -it towards an appliance on a specific interface, while the second -re-encapsulates the traffic coming back from the appliance. - -In this scenario, there are no restrictions on the operations that can be -performed by the appliance on the stream of packets. It may operate at all -protocol layers, terminate transport layer connections, generate new packets and -initiate transport layer connections. This function may also be used to -integrate an IPv4-only appliance into an SRv6 policy. - -The End.AD function relies on a local caching mechanism to learn and -re-encapsulate the traffic with the same headers that were removed. -This cache is used to store the IPv6 header and its -extension headers while the appliance processes the inner packet. In the -following, we refer to an entry in this cache as C(type,iface), where type is -either IPv4 or IPv6 and iface is the receiving interface on the SRv6 proxy -(IFACE-IN). +The dynamic proxy is an improvement over the static proxy (@ref srv6_as_plugin_doc) +that dynamically learns the SR information before removing it from the incoming +traffic. The same information can then be re-attached to the traffic returning +from the SF. As opposed to the static SR proxy, no CACHE information needs to be +configured. Instead, the dynamic SR proxy relies on a local caching mechanism on +the node instantiating this segment. Therefore, a dynamic proxy segment cannot +be the last segment in an SR SC policy. A different SR behavior should thus be +used if the SF is meant to be the final destination of an SR SC policy. + +Upon receiving a packet whose active segment matches a dynamic SR proxy +function, the proxy node pops the top MPLS label or applies the SRv6 End +behavior, then compares the updated SR information with the cache entry for the +current segment. If the cache is empty or different, it is updated with the new +SR information. The SR information is then removed and the inner packet is sent +towards the SF. + +The cache entry is not mapped to any particular packet, but instead to an SR SC +policy identified by the receiving interface (IFACE-IN). Any non-link-local IP +packet or non-local Ethernet frame received on that interface will be +re-encapsulated with the cached headers as described in @ref srv6_as_plugin_doc. The +SF may thus drop, modify or generate new packets without affecting the proxy. + +For more information, please see +[draft-xuclad-spring-sr-service-chaining](https://datatracker.ietf.org/doc/draft-xuclad-spring-sr-service-chaining/). + +## CLI configuration + +The following command instantiates a new End.AD segment that sends the inner +packets on interface `IFACE-OUT` towards an appliance at address `S-ADDR` and +restores the encapsulation headers of the packets coming back on interface +`IFACE-IN`. + +``` +sr localsid address SID behavior end.ad nh S-ADDR oif IFACE-OUT iif IFACE-IN +``` + +For example, the below command configures the SID `1::A1` with an End.AD +function for sending traffic on interface `GigabitEthernet0/8/0` to the +appliance at address `A1::`, and receiving it back on interface +`GigabitEthernet0/9/0`. + +``` +sr localsid address 1::A1 behavior end.ad nh A1:: oif GigabitEthernet0/8/0 iif GigabitEthernet0/9/0 +``` + +## Pseudocode + +The dynamic proxy SRv6 pseudocode is obtained by inserting the following +instructions between lines 1 and 2 of the static proxy SRv6 pseudocode. + +``` +IF NH=SRH & SL > 0 THEN + Decrement SL and update the IPv6 DA with SRH[SL] + IF C(IFACE-IN) different from IPv6 encaps THEN ;; Ref1 + Copy the IPv6 encaps into C(IFACE-IN) ;; Ref2 +ELSE + Drop the packet +``` + +**Ref1:** "IPv6 encaps" represents the IPv6 header and any attached extension +header. + +**Ref2:** C(IFACE-IN) represents the cache entry associated to the dynamic SR proxy +segment. It is identified with IFACE-IN in order to efficiently retrieve the +right SR information when a packet arrives on this interface. + +In addition, the inbound policy should check that C(IFACE-IN) has been defined +before attempting to restore the IPv6 encapsulation, and drop the packet +otherwise. diff --git a/src/plugins/srv6-am/am_plugin_doc.md b/src/plugins/srv6-am/am_plugin_doc.md index d5d18cf99f6..11aad855408 100644 --- a/src/plugins/srv6-am/am_plugin_doc.md +++ b/src/plugins/srv6-am/am_plugin_doc.md @@ -1,91 +1,100 @@ # SRv6 endpoint to SR-unaware appliance via masquerading (End.AM) {#srv6_am_plugin_doc} -## Overview - -The "Endpoint to SR-unaware appliance via masquerading" (End.AM) is a two-parts -function for processing SRv6 **inserted** traffic on behalf of an SR-unaware -appliance. The first part decrements the Segments Left value and **replaces the -IPv6 Destination Address with the last segment in the SRH**, while the second -restores the IPv6 Destination Address with the active segment in the traffic -coming back from the appliance. - -In this scenario, we assume that the appliance can only inspect, drop or perform -limited changes to the packets. In particular, the appliance must not change the -IP Destination Address of the packet, terminate a transport connection nor -generate arbitrary packets. For example, Firewalls, Intrusion Detection Systems, -Deep Packet Inspectors are among the appliances that can be supported in this -scenario. +The masquerading proxy is an SR endpoint behavior for processing SRv6 traffic on +behalf of an SR-unaware SF. This proxy thus receives SR traffic that is formed +of an IPv6 header and an SRH on top of an inner payload. The masquerading +behavior is independent from the inner payload type. Hence, the inner payload +can be of any type but it is usually expected to be a transport layer packet, +such as TCP or UDP. + +A masquerading SR proxy segment is associated with the following mandatory +parameters: + +- S-ADDR: Ethernet or IPv6 address of the SF +- IFACE-OUT: Local interface for sending traffic towards the SF +- IFACE-IN: Local interface receiving the traffic coming back from the SF + +A masquerading SR proxy segment is thus defined for a specific SF and bound to a +pair of directed interfaces or sub-interfaces on the proxy. As opposed to the +static and dynamic SR proxies, a masquerading segment can be present at the same +time in any number of SR SC policies and the same interfaces can be bound to +multiple masquerading proxy segments. The only restriction is that a +masquerading proxy segment cannot be the last segment in an SR SC policy. + +The first part of the masquerading behavior is triggered when the proxy node +receives an IPv6 packet whose Destination Address matches a masquerading proxy +segment. The proxy inspects the IPv6 extension headers and substitutes the +Destination Address with the last segment in the SRH attached to the IPv6 +header, which represents the final destination of the IPv6 packet. The packet is +then sent out towards the SF. + +The SF receives an IPv6 packet whose source and destination addresses are +respectively the original source and final destination. It does not attempt to +inspect the SRH, as RFC8200 specifies that routing extension headers are not +examined or processed by transit nodes. Instead, the SF simply forwards the +packet based on its current Destination Address. In this scenario, we assume +that the SF can only inspect, drop or perform limited changes to the packets. +For example, Intrusion Detection Systems, Deep Packet Inspectors and non-NAT +Firewalls are among the SFs that can be supported by a masquerading SR proxy. + +The second part of the masquerading behavior, also called de- masquerading, is +an inbound policy attached to the proxy interface receiving the traffic +returning from the SF, IFACE-IN. This policy inspects the incoming traffic and +triggers a regular SRv6 endpoint processing (End) on any IPv6 packet that +contains an SRH. This processing occurs before any lookup on the packet +Destination Address is performed and it is sufficient to restore the right +active segment as the Destination Address of the IPv6 packet. + +For more information, please see +[draft-xuclad-spring-sr-service-chaining](https://datatracker.ietf.org/doc/draft-xuclad-spring-sr-service-chaining/). + +## CLI configuration + +The following command instantiates a new End.AM segment that sends masqueraded +traffic on interface `IFACE-OUT` towards an appliance at address `S-ADDR` and +restores the active segment in the IPv6 header of the packets coming back on +interface `IFACE-IN`. -## Pseudo-code +``` +sr localsid address SID behavior end.am nh S-ADDR oif IFACE-OUT iif IFACE-IN +``` -When instantiating an End.AM SID, the following parameters are required: +For example, the below command configures the SID `1::A1` with an End.AM +function for sending traffic on interface `GigabitEthernet0/8/0` to the +appliance at address `A1::`, and receiving it back on interface +`GigabitEthernet0/9/0`. -- APP-ADDR: IP or Ethernet address of the appliance -- IFACE-OUT: local interface for sending traffic towards the appliance -- IFACE-IN: local interface receiving the traffic coming back from the appliance +``` +sr localsid address 1::A1 behavior end.am nh A1:: oif GigabitEthernet0/8/0 iif GigabitEthernet0/9/0 +``` -Packets can be sent to and received from an appliance on the same interface -(IFACE-IN = IFACE-OUT). +## Pseudocode ### Masquerading -Upon receiving a packet destined to S, where S is a local End.AM SID, a node N -does: - - IF NH=SRH & SL > 0 THEN ;; Ref1 - Decrement SL - Write the last SID in the DA - Forward the packet on IFACE-OUT - ELSE - Drop the packet +Upon receiving a packet destined for S, where S is an IPv6 masquerading proxy +segment, a node N processes it as follows. -**Ref1:** an End.AM must not be the last SID. +``` +IF NH=SRH & SL > 0 THEN + Update the IPv6 DA with SRH[0] + Forward the packet on IFACE-OUT +ELSE + Drop the packet +``` ### De-masquerading -Upon receiving a non-link-local IPv6 packet on IFACE-IN, a node N does: - - IF NH=SRH THEN - Replace IP DA with SRH[SL] - Lookup DA in the appropriate table and proceed accordingly - -De-masquerading is a policy attached to IFACE-IN that intercepts all packets -coming back from the appliance and restores the destination address. This -occurs before any lookup on the packet destination address (e.g. in "My Local -SIDs" table or in the FIB) is performed. - -## Benefits - -The End.AM masquerading function brings the following benefits: - -1. The appliance receives a packet with the source and destination addresses -respectively set as the original source and the final destination. -2. The appliance does not try and inspect the SRH, as RFC2460 specifies that -routing extension headers are not examined or processed by transit nodes. - -## Limitations - -An End.AM SID may be present in any number of segment lists at the same time. - -However, since the returning traffic from the appliance is processed based on -the receiving interface (IFACE-IN), this interface may only be bound to a single -End.AM SID at a time. - -In the case of a bi-directional service chain, the same End.AM SID and receiving -interface (IFACE-IN) may be used in both directions. - -## Configuration - -The following CLI instantiates a new End.AM segment that sends masqueraded -traffic on interface `IFACE-OUT` towards an appliance at address `APP-ADDR` and -restores the active segment in the IPv6 header of the packets coming back on -interface `IFACE-IN`. - - sr localsid address SID behavior end.am nh APP-ADDR oif IFACE-OUT iif IFACE-IN - -For example, the following command configures the SID `1::A1` with an End.AM -function for sending traffic on interface `GigabitEthernet0/8/0` to the appliance at -address `A1::`, and receiving it back on interface `GigabitEthernet0/9/0`. +Upon receiving a non-link-local IPv6 packet on IFACE-IN, a node N processes it +as follows. - sr localsid address 1::A1 behavior end.am nh A1:: oif GigabitEthernet0/8/0 iif GigabitEthernet0/9/0 +``` +IF NH=SRH & SL > 0 THEN + Decrement SL + Update the IPv6 DA with SRH[SL] ;; Ref1 + Lookup DA in appropriate table and proceed accordingly +``` +**Ref1:** This pseudocode can be augmented to support the Penultimate Segment +Popping (PSP) endpoint flavor. The exact pseudocode modification are provided in +[draft-filsfils-spring-srv6-network-programming](https://datatracker.ietf.org/doc/draft-filsfils-spring-srv6-network-programming/). diff --git a/src/plugins/srv6-as/as_plugin_doc.md b/src/plugins/srv6-as/as_plugin_doc.md index d8a39496a3d..7cda08b60d9 100644 --- a/src/plugins/srv6-as/as_plugin_doc.md +++ b/src/plugins/srv6-as/as_plugin_doc.md @@ -3,163 +3,150 @@ ## Overview The static proxy is an SR endpoint behavior for processing SR-MPLS or SRv6 -encapsulated traffic on behalf of an SR-unaware service. This proxy thus -receives SR traffic that is formed of an MPLS label stack or an IPv6 header on -top of an inner packet, which can be Ethernet, IPv4 or IPv6. +encapsulated traffic on behalf of an SR-unaware SF. This proxy thus receives SR +traffic that is formed of an MPLS label stack or an IPv6 header on top of an +inner packet, which can be Ethernet, IPv4 or IPv6. A static SR proxy segment is associated with the following mandatory parameters: - INNER-TYPE: Inner packet type -- S-ADDR: Ethernet or IP address of the service (only for inner type IPv4 and - IPv6) -- IFACE-OUT: Local interface for sending traffic towards the service -- IFACE-IN: Local interface receiving the traffic coming back from the service -- CACHE: SR information to be attached on the traffic coming back from the - service - -A static SR proxy segment is thus defined for a specific service, inner packet -type and cached SR information. It is also bound to a pair of directed -interfaces on the proxy. These may be both directions of a single interface, or -opposite directions of two different interfaces. The latter is recommended in -case the service is to be used as part of a bi-directional SR SC policy. If the -proxy and the service both support 802.1Q, IFACE-OUT and IFACE-IN can also -represent sub-interfaces. +- S-ADDR: Ethernet or IP address of the SF (only for inner type IPv4 and IPv6) +- IFACE-OUT: Local interface for sending traffic towards the SF +- IFACE-IN: Local interface receiving the traffic coming back from the SF +- CACHE: SR information to be attached on the traffic coming back from the SF, +including at least + * CACHE.SA: IPv6 source address (SRv6 only) + * CACHE.LIST: Segment list expressed as MPLS labels or IPv6 address + +A static SR proxy segment is thus defined for a specific SF, inner packet type +and cached SR information. It is also bound to a pair of directed interfaces on +the proxy. These may be both directions of a single interface, or opposite +directions of two different interfaces. The latter is recommended in case the SF +is to be used as part of a bi-directional SR SC policy. If the proxy and the SF +both support 802.1Q, IFACE-OUT and IFACE-IN can also represent sub-interfaces. The first part of this behavior is triggered when the proxy node receives a packet whose active segment matches a segment associated with the static proxy -behavior. It removes the SR information from the packet then sends it on a -specific interface towards the associated service. This SR information -corresponds to the full label stack for SR-MPLS or to the encapsulation IPv6 -header with any attached extension header in the case of SRv6. +behavior. It removes the SR information from the packet then sends it on a +specific interface towards the associated SF. This SR information corresponds to +the full label stack for SR-MPLS or to the encapsulation IPv6 header with any +attached extension header in the case of SRv6. The second part is an inbound policy attached to the proxy interface receiving -the traffic returning from the service, IFACE-IN. This policy attaches to the +the traffic returning from the SF, IFACE-IN. This policy attaches to the incoming traffic the cached SR information associated with the SR proxy segment. If the proxy segment uses the SR-MPLS data plane, CACHE contains a stack of -labels to be pushed on top the packets. With the SRv6 data plane, CACHE is +labels to be pushed on top the packets. With the SRv6 data plane, CACHE is defined as a source address, an active segment and an optional SRH (tag, -segments left, segment list and metadata). The proxy encapsulates the packets +segments left, segment list and metadata). The proxy encapsulates the packets with an IPv6 header that has the source address, the active segment as -destination address and the SRH as a routing extension header. After the SR +destination address and the SRH as a routing extension header. After the SR information has been attached, the packets are forwarded according to the active segment, which is represented by the top MPLS label or the IPv6 Destination Address. In this scenario, there are no restrictions on the operations that can be -performed by the service on the stream of packets. It may operate at all -protocol layers, terminate transport layer connections, generate new packets and -initiate transport layer connections. This behavior may also be used to -integrate an IPv4-only service into an SRv6 policy. However, a static SR proxy -segment can be used in only one service chain at a time. As opposed to most -other segment types, a static SR proxy segment is bound to a unique list of -segments, which represents a directed SR SC policy. This is due to the cached -SR information being defined in the segment configuration. This limitation only -prevents multiple segment lists from using the same static SR proxy segment at -the same time, but a single segment list can be shared by any number of traffic -flows. Besides, since the returning traffic from the service is re- classified -based on the incoming interface, an interface can be used as receiving interface -(IFACE-IN) only for a single SR proxy segment at a time. In the case of a -bi-directional SR SC policy, a different SR proxy segment and receiving -interface are required for the return direction. - -## SRv6 pseudocode - -### Static proxy for inner type Ethernet - End.AS2 - -Upon receiving an IPv6 packet destined for S, where S is an End.AS2 SID, a node -N does: +performed by the SF on the stream of packets. It may operate at all protocol +layers, terminate transport layer connections, generate new packets and initiate +transport layer connections. This behavior may also be used to integrate an +IPv4-only SF into an SRv6 policy. However, a static SR proxy segment can be used +in only one service chain at a time. As opposed to most other segment types, a +static SR proxy segment is bound to a unique list of segments, which represents +a directed SR SC policy. This is due to the cached SR information being defined +in the segment configuration. This limitation only prevents multiple segment +lists from using the same static SR proxy segment at the same time, but a single +segment list can be shared by any number of traffic flows. Besides, since the +returning traffic from the SF is re-classified based on the incoming interface, +an interface can be used as receiving interface (IFACE-IN) only for a single SR +proxy segment at a time. In the case of a bi-directional SR SC policy, a +different SR proxy segment and receiving interface are required for the return +direction. + +For more information, please see +[draft-xuclad-spring-sr-service-chaining](https://datatracker.ietf.org/doc/draft-xuclad-spring-sr-service-chaining/). + +## CLI configuration + +The following command instantiates a new End.AS segment that sends the inner +packets on interface `IFACE-OUT` towards an appliance at address `S-ADDR` and +restores the segment list ``<S1, S2, S3>`` with a source address `SRC-ADDR` on +the packets coming back on interface `IFACE-IN`. ``` - 1. IF ENH == 59 THEN ;; Ref1 - 2. Remove the (outer) IPv6 header and its extension headers - 3. Forward the exposed frame on IFACE-OUT - 4. ELSE - 5. Drop the packet +sr localsid address SID behavior end.ad nh S-ADDR oif IFACE-OUT iif IFACE-IN src SRC-ADDR next S1 next S2 next S3 ``` -Ref1: 59 refers to "no next header" as defined by IANA allocation for Internet -Protocol Numbers. - -Upon receiving on IFACE-IN an Ethernet frame with a destination address -different than the interface address, a node N does: +For example, the below command configures the SID `1::A1` with an End.AS +function for sending traffic on interface `GigabitEthernet0/8/0` to the +appliance at address `A1::`, and receiving it back on interface +`GigabitEthernet0/9/0`. ``` - 1. IF CACHE.SRH THEN ;; Ref2 - 2. Push CACHE.SRH on top of the existing Ethernet header - 3. Set NH value of the pushed SRH to 59 - 4. Push outer IPv6 header with SA, DA and traffic class from CACHE - 5. Set outer payload length and flow label - 6. Set NH value to 43 if an SRH was added, or 59 otherwise - 7. Lookup outer DA in appropriate table and proceed accordingly +sr localsid address 1::A1 behavior end.ad nh A1:: oif GigabitEthernet0/8/0 iif GigabitEthernet0/9/0 src 1:: next 2::20 next 3::30 next 4::40 ``` -Ref2: CACHE.SRH represents the SRH defined in CACHE, if any, for the static SR -proxy segment associated with IFACE-IN. +## Pseudocode -The receiving interface must be configured in promiscuous mode in order to -accept those Ethernet frames. +### Static proxy for inner type IPv4 -### Static proxy for inner type IPv4 - End.AS4 - -Upon receiving an IPv6 packet destined for S, where S is an End.AS4 SID, a node -N does: +Upon receiving an IPv6 packet destined for S, where S is an IPv6 static proxy +segment for IPv4 traffic, a node N does: ``` - 1. IF ENH == 4 THEN ;; Ref1 - 2. Remove the (outer) IPv6 header and its extension headers - 3. Forward the exposed packet on IFACE-OUT towards S-ADDR - 4. ELSE - 5. Drop the packet +IF ENH == 4 THEN ;; Ref1 + Remove the (outer) IPv6 header and its extension headers + Forward the exposed packet on IFACE-OUT towards S-ADDR +ELSE + Drop the packet ``` -Ref1: 4 refers to IPv4 encapsulation as defined by IANA allocation for Internet +**Ref1:** 4 refers to IPv4 encapsulation as defined by IANA allocation for Internet Protocol Numbers. Upon receiving a non link-local IPv4 packet on IFACE-IN, a node N does: ``` - 1. IF CACHE.SRH THEN ;; Ref2 - 2. Push CACHE.SRH on top of the existing IPv4 header - 3. Set NH value of the pushed SRH to 4 - 4. Push outer IPv6 header with SA, DA and traffic class from CACHE - 5. Set outer payload length and flow label - 6. Set NH value to 43 if an SRH was added, or 4 otherwise - 7. Decrement inner TTL and update checksum - 8. Lookup outer DA in appropriate table and proceed accordingly +Decrement TTL and update checksum +IF CACHE.SRH THEN ;; Ref2 + Push CACHE.SRH on top of the existing IPv4 header + Set NH value of the pushed SRH to 4 +Push outer IPv6 header with SA, DA and traffic class from CACHE +Set outer payload length and flow label +Set NH value to 43 if an SRH was added, or 4 otherwise +Lookup outer DA in appropriate table and proceed accordingly ``` -Ref2: CACHE.SRH represents the SRH defined in CACHE, if any, for the static SR +**Ref2:** CACHE.SRH represents the SRH defined in CACHE, if any, for the static SR proxy segment associated with IFACE-IN. -### Static proxy for inner type IPv6 - End.AS6 +### Static proxy for inner type IPv6 -Upon receiving an IPv6 packet destined for S, where S is an End.AS6 SID, a node -N does: +Upon receiving an IPv6 packet destined for S, where S is an IPv6 static proxy +segment for IPv6 traffic, a node N does: ``` - 1. IF ENH == 41 THEN ;; Ref1 - 2. Remove the (outer) IPv6 header and its extension headers - 3. Forward the exposed packet on IFACE-OUT towards S-ADDR - 4. ELSE - 5. Drop the packet +IF ENH == 41 THEN ;; Ref1 + Remove the (outer) IPv6 header and its extension headers + Forward the exposed packet on IFACE-OUT towards S-ADDR +ELSE + Drop the packet ``` -Ref1: 41 refers to IPv6 encapsulation as defined by IANA allocation for Internet +**Ref1:** 41 refers to IPv6 encapsulation as defined by IANA allocation for Internet Protocol Numbers. Upon receiving a non-link-local IPv6 packet on IFACE-IN, a node N does: ``` - 1. IF CACHE.SRH THEN ;; Ref2 - 2. Push CACHE.SRH on top of the existing IPv6 header - 3. Set NH value of the pushed SRH to 41 - 4. Push outer IPv6 header with SA, DA and traffic class from CACHE - 5. Set outer payload length and flow label - 6. Set NH value to 43 if an SRH was added, or 41 otherwise - 7. Decrement inner Hop Limit - 8. Lookup outer DA in appropriate table and proceed accordingly +Decrement Hop Limit +IF CACHE.SRH THEN ;; Ref2 + Push CACHE.SRH on top of the existing IPv6 header + Set NH value of the pushed SRH to 41 +Push outer IPv6 header with SA, DA and traffic class from CACHE +Set outer payload length and flow label +Set NH value to 43 if an SRH was added, or 41 otherwise +Lookup outer DA in appropriate table and proceed accordingly ``` -Ref2: CACHE.SRH represents the SRH defined in CACHE, if any, for the static SR +**Ref2:** CACHE.SRH represents the SRH defined in CACHE, if any, for the static SR proxy segment associated with IFACE-IN. - |