From f47122e07e1ecd0151902a3cabe46c60a99bee8e Mon Sep 17 00:00:00 2001 From: Nathan Skrzypczak Date: Fri, 8 Oct 2021 14:05:35 +0200 Subject: docs: convert plugins doc md->rst Type: improvement Change-Id: I7e821cce1feae229e1be4baeed249b9cca658135 Signed-off-by: Nathan Skrzypczak --- src/plugins/nat/nat44-ei/nat44_ei_ha_doc.md | 70 --------------------- src/plugins/nat/nat44-ei/nat44_ei_ha_doc.rst | 88 +++++++++++++++++++++++++++ src/plugins/nat/nat64/nat64_doc.md | 73 ---------------------- src/plugins/nat/nat64/nat64_doc.rst | 91 ++++++++++++++++++++++++++++ src/plugins/nat/pnat/pnat.md | 37 ----------- src/plugins/nat/pnat/pnat.rst | 45 ++++++++++++++ 6 files changed, 224 insertions(+), 180 deletions(-) delete mode 100644 src/plugins/nat/nat44-ei/nat44_ei_ha_doc.md create mode 100644 src/plugins/nat/nat44-ei/nat44_ei_ha_doc.rst delete mode 100644 src/plugins/nat/nat64/nat64_doc.md create mode 100644 src/plugins/nat/nat64/nat64_doc.rst delete mode 100644 src/plugins/nat/pnat/pnat.md create mode 100644 src/plugins/nat/pnat/pnat.rst (limited to 'src/plugins/nat') diff --git a/src/plugins/nat/nat44-ei/nat44_ei_ha_doc.md b/src/plugins/nat/nat44-ei/nat44_ei_ha_doc.md deleted file mode 100644 index f0ea209e250..00000000000 --- a/src/plugins/nat/nat44-ei/nat44_ei_ha_doc.md +++ /dev/null @@ -1,70 +0,0 @@ -# Active-Passive NAT HA {#nat_ha_doc} - -## Introduction - -One NAT node actively manages traffic while the other is synchronized and ready to transition to the active state and takes over seamlessly and enforces the same NAT sessions when failure occur. Both nodes share the same configuration settings. - -## Configuration - -### NAT HA protocol -Session synchronization traffic is distributed through an IPv4 UDP connection. The active node sends NAT HA protocol events to passive node. To achieve reliable transfer NAT HA protocol uses acknowledgement with re-transmission. This require the passive node to respond with an acknowledgement message as it receives the data. The active node keeps a record of each packet it sends and maintains a timer from when the packet was sent. The active node re-transmits a packet if the timer expires before receiving the acknowledgement. - -### Topology - -The two NAT nodes have a dedicated link (interface GE0/0/3 on both) to synchronize NAT sessions using NAT HA protocol. - -``` - +-----------------------+ - | outside network | - +-----------------------+ - / \ - / \ - / \ - / \ - / \ -+---------+ +---------+ -| GE0/0/1 | Active Passive | GE0/0/1 | -| | | | -| GE0/0/3|-------------------|GE0/0/3 | -| | sync network | | -| GE0/0/0 | | GE0/0/0 | -+---------+ +---------+ - \ / - \ / - \ / - \ / - \ / - +-----------------------+ - | inside network | - +-----------------------+ -``` - -### Active node configuration - -``` -set interface ip address GigabitEthernet0/0/1 10.15.7.101/24 -set interface ip address GigabitEthernet0/0/0 172.16.10.101/24 -set interface ip address GigabitEthernet0/0/3 10.0.0.1/24 -set interface state GigabitEthernet0/0/0 up -set interface state GigabitEthernet0/0/1 up -set interface state GigabitEthernet0/0/3 up -set interface nat44 in GigabitEthernet0/0/0 out GigabitEthernet0/0/1 -nat44 add address 10.15.7.100 -nat ha listener 10.0.0.1:1234 -nat ha failover 10.0.0.2:2345 -``` - -### Passive node configuration - -``` -set interface ip address GigabitEthernet0/0/1 10.15.7.102/24 -set interface ip address GigabitEthernet0/0/0 172.16.10.102/24 -set interface ip address GigabitEthernet0/0/3 10.0.0.2/24 -set interface state GigabitEthernet0/0/0 up -set interface state GigabitEthernet0/0/1 up -set interface state GigabitEthernet0/0/3 up -set interface nat44 in GigabitEthernet0/0/0 out GigabitEthernet0/0/1 -nat44 add address 10.15.7.100 -nat ha listener 10.0.0.2:2345 -``` - diff --git a/src/plugins/nat/nat44-ei/nat44_ei_ha_doc.rst b/src/plugins/nat/nat44-ei/nat44_ei_ha_doc.rst new file mode 100644 index 00000000000..46befc52351 --- /dev/null +++ b/src/plugins/nat/nat44-ei/nat44_ei_ha_doc.rst @@ -0,0 +1,88 @@ +Active-Passive NAT HA +===================== + +Introduction +------------ + +One NAT node actively manages traffic while the other is synchronized +and ready to transition to the active state and takes over seamlessly +and enforces the same NAT sessions when failure occur. Both nodes share +the same configuration settings. + +Configuration +------------- + +NAT HA protocol +~~~~~~~~~~~~~~~ + +Session synchronization traffic is distributed through an IPv4 UDP +connection. The active node sends NAT HA protocol events to passive +node. To achieve reliable transfer NAT HA protocol uses acknowledgment +with re-transmission. This require the passive node to respond with an +acknowledgment message as it receives the data. The active node keeps a +record of each packet it sends and maintains a timer from when the +packet was sent. The active node re-transmits a packet if the timer +expires before receiving the acknowledgment. + +Topology +~~~~~~~~ + +The two NAT nodes have a dedicated link (interface GE0/0/3 on both) to +synchronize NAT sessions using NAT HA protocol. + +:: + + +-----------------------+ + | outside network | + +-----------------------+ + / \ + / \ + / \ + / \ + / \ + +---------+ +---------+ + | GE0/0/1 | Active Passive | GE0/0/1 | + | | | | + | GE0/0/3|-------------------|GE0/0/3 | + | | sync network | | + | GE0/0/0 | | GE0/0/0 | + +---------+ +---------+ + \ / + \ / + \ / + \ / + \ / + +-----------------------+ + | inside network | + +-----------------------+ + +Active node configuration +~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + set interface ip address GigabitEthernet0/0/1 10.15.7.101/24 + set interface ip address GigabitEthernet0/0/0 172.16.10.101/24 + set interface ip address GigabitEthernet0/0/3 10.0.0.1/24 + set interface state GigabitEthernet0/0/0 up + set interface state GigabitEthernet0/0/1 up + set interface state GigabitEthernet0/0/3 up + set interface nat44 in GigabitEthernet0/0/0 out GigabitEthernet0/0/1 + nat44 add address 10.15.7.100 + nat ha listener 10.0.0.1:1234 + nat ha failover 10.0.0.2:2345 + +Passive node configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + set interface ip address GigabitEthernet0/0/1 10.15.7.102/24 + set interface ip address GigabitEthernet0/0/0 172.16.10.102/24 + set interface ip address GigabitEthernet0/0/3 10.0.0.2/24 + set interface state GigabitEthernet0/0/0 up + set interface state GigabitEthernet0/0/1 up + set interface state GigabitEthernet0/0/3 up + set interface nat44 in GigabitEthernet0/0/0 out GigabitEthernet0/0/1 + nat44 add address 10.15.7.100 + nat ha listener 10.0.0.2:2345 diff --git a/src/plugins/nat/nat64/nat64_doc.md b/src/plugins/nat/nat64/nat64_doc.md deleted file mode 100644 index f65b46338b0..00000000000 --- a/src/plugins/nat/nat64/nat64_doc.md +++ /dev/null @@ -1,73 +0,0 @@ -# Stateful NAT64: Network Address and Protocol Translation from IPv6 Clients to IPv4 Servers {#nat64_doc} - -## Introduction - -Stateful NAT64 in VPP allows IPv6-only clients to contact IPv4 servers using unicast UDP, TCP, or ICMP based on RFC 6146. - -## Configuration - -### Enable/disable NAT64 feature on the interface - -> set interface nat64 in|out [del] - -in: inside/local/IPv6 network -out: outside/external/IPv4 network -intfc: interface name - -### Add/delete NAT64 pool address - -One or more public IPv4 addresses assigned to a NAT64 are shared among several IPv6-only clients. - -> nat64 add pool address [- ] [tenant-vrf ] [del] - -ip4-range-start: First IPv4 address of the range -ip4-range-end: Last IPv4 address of the range (optional, not used for single address) -tenant-vrf-id: VRF id of the tenant associated with the pool address (optional, if not set pool address is global) - -### Add/delete static BIB entry - -Stateful NAT64 also supports IPv4-initiated communications to a subset of the IPv6 hosts through staticaly configured bindings. - -> nat64 add static bib tcp|udp|icmp [vfr ] [del] - -ip6-addr: inside IPv6 address of the host -in-port: inside port or ICMPv6 identifier -ip4-addr: outside IPv4 address of the host -out-port: outside port or ICMPv4 identifier -table-id: VRF id of the tenant associated with the BIB entry (optional, default use global VRF) - -### Set NAT64 session timeouts - -Session is deleted when timer expires. If all sessions corresponding to a dynamically create BIB entry are deleted, then the BIB entry is also deleted. When packets are flowing sessiom timer is refreshed to keep the session alive. - -> set nat64 timeouts udp icmp tcp-trans tcp-est tcp-incoming-syn | reset - -udp: UDP session timeout value (default 300sec) -icmp: ICMP session timeout value (default 60sec) -tcp-trans: transitory TCP session timeout value (default 240sec) -tcp-est: established TCP session timeout value (default 7440sec) -tcp-incoming-syn: incoming SYN TCP session timeout value (default 6sec) -reset: reset timers to default values - -### Set NAT64 prefix - -Stateful NAT64 support the algorithm for generating IPv6 representations of IPv4 addresses defined in RFC 6052. If no prefix is configured, Well-Known Prefix (64:ff9b::/96) is used. - -> nat64 add prefix / [tenant-vrf ] [del] - -ip6-prefix: IPv6 prefix -plen: prefix length (valid values: 32, 40, 48, 56, 64, or 96) -tenant-vrf: VRF id of the tenant associated with the prefix - -### Show commands - -> show nat64 pool -> show nat64 interfaces -> show nat64 bib tcp|udp|icmp -> show nat64 session table tcp|udp|icmp -> show nat64 timeouts -> show nat64 prefix - -## Notes - -Multi thread is not supported yet (CLI/API commands are disabled when VPP runs with multiple threads). diff --git a/src/plugins/nat/nat64/nat64_doc.rst b/src/plugins/nat/nat64/nat64_doc.rst new file mode 100644 index 00000000000..f375fba68bd --- /dev/null +++ b/src/plugins/nat/nat64/nat64_doc.rst @@ -0,0 +1,91 @@ +Stateful NAT64 +============== + +This document describes stateful NAT64 Network Address and Protocol +Translation + +Introduction +------------ + +Stateful NAT64 in VPP allows IPv6-only clients to contact IPv4 servers +using unicast UDP, TCP, or ICMP based on RFC 6146. + +Configuration +------------- + +Enable/disable NAT64 feature on the interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + set interface nat64 in|out [del] + +in: inside/local/IPv6 network out: outside/external/IPv4 network intfc: +interface name + +Add/delete NAT64 pool address +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +One or more public IPv4 addresses assigned to a NAT64 are shared among +several IPv6-only clients. + + nat64 add pool address [- ] [tenant-vrf ] [del] + +ip4-range-start: First IPv4 address of the range ip4-range-end: Last +IPv4 address of the range (optional, not used for single address) +tenant-vrf-id: VRF id of the tenant associated with the pool address +(optional, if not set pool address is global) + +Add/delete static BIB entry +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Stateful NAT64 also supports IPv4-initiated communications to a subset +of the IPv6 hosts through statically configured bindings. + + nat64 add static bib tcp|udp|icmp [vfr ] [del] + +ip6-addr: inside IPv6 address of the host in-port: inside port or ICMPv6 +identifier ip4-addr: outside IPv4 address of the host out-port: outside +port or ICMPv4 identifier table-id: VRF id of the tenant associated with +the BIB entry (optional, default use global VRF) + +Set NAT64 session timeouts +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Session is deleted when timer expires. If all sessions corresponding to +a dynamically create BIB entry are deleted, then the BIB entry is also +deleted. When packets are flowing session timer is refreshed to keep the +session alive. + + set nat64 timeouts udp icmp tcp-trans tcp-est tcp-incoming-syn \| + reset + +udp: UDP session timeout value (default 300sec) icmp: ICMP session +timeout value (default 60sec) tcp-trans: transitory TCP session timeout +value (default 240sec) tcp-est: established TCP session timeout value +(default 7440sec) tcp-incoming-syn: incoming SYN TCP session timeout +value (default 6sec) reset: reset timers to default values + +Set NAT64 prefix +~~~~~~~~~~~~~~~~ + +Stateful NAT64 support the algorithm for generating IPv6 representations +of IPv4 addresses defined in RFC 6052. If no prefix is configured, +Well-Known Prefix (64:ff9b::/96) is used. + + nat64 add prefix / [tenant-vrf ] [del] + +ip6-prefix: IPv6 prefix plen: prefix length (valid values: 32, 40, 48, +56, 64, or 96) tenant-vrf: VRF id of the tenant associated with the +prefix + +Show commands +~~~~~~~~~~~~~ + + show nat64 pool show nat64 interfaces show nat64 bib tcp|udp|icmp + show nat64 session table tcp|udp|icmp show nat64 timeouts show nat64 + prefix + +Notes +----- + +Multi thread is not supported yet (CLI/API commands are disabled when +VPP runs with multiple threads). diff --git a/src/plugins/nat/pnat/pnat.md b/src/plugins/nat/pnat/pnat.md deleted file mode 100644 index 1e6bc130848..00000000000 --- a/src/plugins/nat/pnat/pnat.md +++ /dev/null @@ -1,37 +0,0 @@ -# PNAT: 1:1 match and rewrite programmable NAT {#pnat_doc} - -PNAT is a stateless statically configured, match and rewrite plugin. -It uses a set of match and rewrite rules that are applied on the IP -input and output feature paths. A PNAT rule is unidirectional. - -The match is done using up to a 6-tuple; IP source and destination address, -IP protocol, transport layer source and destination ports, and FIB table / interface index. - -While multiple match/rewrite rules can be applied to an interface (per direction), the match -pattern must be the same across all rules on that interface/direction. - -If required in the future, matching could be done using the general classifier, allowing matching -on any protocol field, as well having an ordered set of match patterns. - -If the packet does not match, it will by default be passed to the next graph node in the feature chain. -If desired a different miss behaviour could be implemented, e.g. similarly to dynamic NAT, the packet punted to a slow path. - -## Rewrite instructions - -``` c -typedef enum { - PNAT_INSTR_NONE = 1 << 0, - PNAT_INSTR_SOURCE_ADDRESS = 1 << 1, - PNAT_INSTR_SOURCE_PORT = 1 << 2, - PNAT_INSTR_DESTINATION_ADDRESS = 1 << 3, - PNAT_INSTR_DESTINATION_PORT = 1 << 4, -} pnat_instructions_t; -``` - -These are the supported rewrite instructions. -The IP checksum and the TCP/UDP checksum are incrementally updated as required. - -There are only a few "sanity checks" on the rewrites. For example, the rewrite in the outbound direction -is applied on the ip-output feature chain. If one were to rewrite the IP destination address, the routing -decision and determination of the next-hop has already been done, and the packet would still be forwarded -to the original next-hop. diff --git a/src/plugins/nat/pnat/pnat.rst b/src/plugins/nat/pnat/pnat.rst new file mode 100644 index 00000000000..5cac047a236 --- /dev/null +++ b/src/plugins/nat/pnat/pnat.rst @@ -0,0 +1,45 @@ +PNAT 1:1 match & rewrite NAT +============================ + +PNAT is a stateless statically configured, match and rewrite plugin. It +uses a set of match and rewrite rules that are applied on the IP input +and output feature paths. A PNAT rule is unidirectional. + +The match is done using up to a 6-tuple; IP source and destination +address, IP protocol, transport layer source and destination ports, and +FIB table / interface index. + +While multiple match/rewrite rules can be applied to an interface (per +direction), the match pattern must be the same across all rules on that +interface/direction. + +If required in the future, matching could be done using the general +classifier, allowing matching on any protocol field, as well having an +ordered set of match patterns. + +If the packet does not match, it will by default be passed to the next +graph node in the feature chain. If desired a different miss behaviour +could be implemented, e.g. similarly to dynamic NAT, the packet punted +to a slow path. + +Rewrite instructions +-------------------- + +.. code:: c + + typedef enum { + PNAT_INSTR_NONE = 1 << 0, + PNAT_INSTR_SOURCE_ADDRESS = 1 << 1, + PNAT_INSTR_SOURCE_PORT = 1 << 2, + PNAT_INSTR_DESTINATION_ADDRESS = 1 << 3, + PNAT_INSTR_DESTINATION_PORT = 1 << 4, + } pnat_instructions_t; + +These are the supported rewrite instructions. The IP checksum and the +TCP/UDP checksum are incrementally updated as required. + +There are only a few “sanity checks” on the rewrites. For example, the +rewrite in the outbound direction is applied on the ip-output feature +chain. If one were to rewrite the IP destination address, the routing +decision and determination of the next-hop has already been done, and +the packet would still be forwarded to the original next-hop. -- cgit 1.2.3-korg