docs: Restore and update nat section of progressive tutorial

The NAT section of the Progressive Tutorial was likely accidentally lost
in If5b0d07ea90d978c6b1f11210a661876b7929653. This patch restores it. It
is also updated to reflect current package and plugin names and cli
reference links.

Type: docs
Change-Id: Ifb6117cd00768fd05dccfa506b4e97c81f9bcf21
Signed-off-by: Bence Romsics <[email protected]>

diff --git a/docs/_images/SNAT_Topology.jpg b/docs/_images/NAT_Topology.jpg
similarity index 100%
rename from docs/_images/SNAT_Topology.jpg
rename to docs/_images/NAT_Topology.jpg

diff --git a/docs/gettingstarted/progressivevpp/index.rst b/docs/gettingstarted/progressivevpp/index.rst
index efe31b1..e35daf6 100644 (file)
--- a/docs/gettingstarted/progressivevpp/index.rst
+++ b/docs/gettingstarted/progressivevpp/index.rst
@@ -23,3 +23,4 @@ will discuss basic operations, and the state of a running FD.io VPP on a system.
    twovppinstances.rst
    routing.rst
    switching.rst
+   nat.rst

diff --git a/docs/gettingstarted/progressivevpp/nat.rst b/docs/gettingstarted/progressivevpp/nat.rst
new file mode 100644 (file)
index 0000000..52f2a76
--- /dev/null
+++ b/docs/gettingstarted/progressivevpp/nat.rst
@@ -0,0 +1,159 @@
+.. _nat:
+
+.. toctree::
+
+Network Address Translation
+===========================
+
+Skills to be Learned
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Abusing networks namespaces for fun and profit
+#. Configuring nat address
+#. Configuring nat inside and outside interfaces
+
+FD.io VPP command learned in this exercise
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. `nat44 add interface address
+   <https://fd.io/docs/vpp/master/cli-reference/clis/clicmd_src_plugins_nat_nat44-ed.html#nat44-add-interface-address>`__
+#. `set interface nat44
+   <https://fd.io/docs/vpp/master/cli-reference/clis/clicmd_src_plugins_nat_nat44-ed.html#set-interface-nat44>`__
+
+Topology
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: /_images/NAT_Topology.jpg
+   :alt: NAT Topology
+
+   NAT Topology
+
+Initial state
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Unlike previous exercises, for this one you want to start tabula rasa.
+
+Note: You will lose all your existing config in your FD.io VPP instances!
+
+To clear existing config from previous exercises run:
+
+.. code-block:: console
+
+   ps -ef | grep vpp | awk '{print $2}'| xargs sudo kill
+   $ sudo ip link del dev vpp1host
+   $ sudo ip link del dev vpp1vpp2
+
+Install vpp-plugins
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+NAT is supported by a plugin, so the respective package needs to be installed
+
+.. code-block:: console
+
+   $ sudo apt-get install vpp-plugin-core
+
+Create FD.io VPP  instance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create one FD.io VPP instance named vpp1.
+
+Confirm nat44 plugin is present:
+
+.. code-block:: console
+
+    # vppctl -s /run/vpp/cli-vpp1.sock show plugins | egrep nat44
+    57. nat44_ei_plugin.so                       24.02-rc0~124-g2ab902f28         IPv4 Endpoint-Independent NAT (NAT44 EI)
+
+Please note that earlier versions if VPP and this document referred to the
+``snat`` plugin, which `was renamed <https://www.mail-archive.com/[email protected]/msg03299.html>`__.
+
+Create veth interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Create a veth interface with one end named ``vpp1outside`` and the other
+   named ``vpp1outsidehost``
+#. Assign IP address 10.10.1.1/24 to ``vpp1outsidehost``
+#. Create a veth interface with one end named ``vpp1inside`` and the other
+   named ``vpp1insidehost``
+#. Assign IP address 10.10.2.1/24 to ``vpp1insidehost``
+
+Because we'd like to be able to route \*via\* our vpp instance to an
+interface on the same host, we are going to put ``vpp1insidehost`` into a
+network namespace
+
+Create a new network namespace 'inside'
+
+.. code-block:: console
+
+    $ sudo ip netns add inside
+
+Move interface vpp1inside into the 'inside' namespace:
+
+.. code-block:: console
+
+    $ sudo ip link set dev vpp1insidehost up netns inside
+
+Assign an ip address to ``vpp1insidehost``
+
+.. code-block:: console
+
+    $ sudo ip netns exec inside ip addr add 10.10.2.1/24 dev vpp1insidehost
+
+Create a route inside the ``netns``:
+
+.. code-block:: console
+
+    $ sudo ip netns exec inside ip route add 10.10.1.0/24 via 10.10.2.2
+
+Configure vpp outside interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Create a vpp host interface connected to vpp1outside
+#. Assign ip address 10.10.1.2/24
+#. Create a vpp host interface connected to vpp1inside
+#. Assign ip address 10.10.2.2/24
+
+Configure nat44
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enable the nat44 plugin
+
+.. code-block:: console
+
+   vpp# nat44 plugin enable
+
+Configure nat44 to use the address of host-vpp1outside
+
+.. code-block:: console
+
+   vpp# nat44 add interface address host-vpp1outside
+
+Configure nat44 inside and outside interfaces
+
+.. code-block:: console
+
+   vpp# set interface nat44 in host-vpp1inside out host-vpp1outside
+
+Prepare to Observe NAT
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Observing NAT in this configuration is interesting. To do so, vagrant
+ssh a second time into your VM and run:
+
+.. code-block:: console
+
+   $ sudo tcpdump -s 0 -i vpp1outsidehost
+
+Also enable tracing on vpp1
+
+Ping via NAT
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+   $ sudo ip netns exec inside ping -c 3 10.10.1.1
+
+Confirm NAT
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Examine the ``tcpdump`` output and vpp1 trace to confirm NAT occurred.