docs: better docs, mv doxygen to sphinx

This patch refactors the VPP sphinx docs
in order to make it easier to consume
for external readers as well as VPP developers.

It also makes sphinx the single source
of documentation, which simplifies maintenance
and operation.

Most important updates are:

- reformat the existing documentation as rst
- split RELEASE.md and move it into separate rst files
- remove section 'events'
- remove section 'archive'
- remove section 'related projects'
- remove section 'feature by release'
- remove section 'Various links'
- make (Configuration reference, CLI docs,
  developer docs) top level items in the list
- move 'Use Cases' as part of 'About VPP'
- move 'Troubleshooting' as part of 'Getting Started'
- move test framework docs into 'Developer Documentation'
- add a 'Contributing' section for gerrit,
  docs and other contributer related infos
- deprecate doxygen and test-docs targets
- redirect the "make doxygen" target to "make docs"

Type: refactor

Change-Id: I552a5645d5b7964d547f99b1336e2ac24e7c209f
Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>
Signed-off-by: Andrew Yourtchenko <ayourtch@gmail.com>

4 files changed, 547 insertions, 0 deletions

diff --git a/docs/usecases/ikev2/2_vpp.rst b/docs/usecases/ikev2/2_vpp.rst
new file mode 100644
index 00000000000..2c6fe6b88e4
--- /dev/null
+++ b/docs/usecases/ikev2/2_vpp.rst
@@ -0,0 +1,128 @@
+How to connect VPP instances using IKEv2
+========================================
+
+This section describes how to initiate IKEv2 session between two VPP
+instances using Linux veth interfaces and namespaces.
+
+Create veth interfaces and namespaces and configure it:
+
+::
+
+   sudo ip link add ifresp type veth peer name ifinit
+   sudo ip link set dev ifresp up
+   sudo ip link set dev ifinit up
+
+   sudo ip netns add clientns
+   sudo ip netns add serverns
+   sudo ip link add veth_client type veth peer name client
+   sudo ip link add veth_server type veth peer name server
+   sudo ip link set dev veth_client up netns clientns
+   sudo ip link set dev veth_server up netns serverns
+
+   sudo ip netns exec clientns \
+         bash -c "
+                 ip link set dev lo up
+                 ip addr add 192.168.5.2/24 dev veth_client
+                 ip addr add fec5::2/16 dev veth_client
+                 ip route add 192.168.3.0/24 via 192.168.5.1
+                 ip route add fec3::0/16 via fec5::1
+         "
+
+   sudo ip netns exec serverns \
+         bash -c "
+                 ip link set dev lo up
+                 ip addr add 192.168.3.2/24 dev veth_server
+                 ip addr add fec3::2/16 dev veth_server
+                 ip route add 192.168.5.0/24 via 192.168.3.1
+                 ip route add fec5::0/16 via fec3::1
+         "
+
+Run responder VPP:
+
+::
+
+   sudo /usr/bin/vpp unix { \
+         cli-listen /tmp/vpp_resp.sock \
+         gid $(id -g) } \
+         api-segment { prefix vpp } \
+         plugins { plugin dpdk_plugin.so { disable } }
+
+Configure the responder
+
+::
+
+   create host-interface name ifresp
+   set interface ip addr host-ifresp 192.168.10.2/24
+   set interface state host-ifresp up
+
+   create host-interface name server
+   set interface ip addr host-server 192.168.3.1/24
+   set interface state host-server up
+
+   ikev2 profile add pr1
+   ikev2 profile set pr1 auth shared-key-mic string Vpp123
+   ikev2 profile set pr1 id local ipv4 192.168.10.2
+   ikev2 profile set pr1 id remote ipv4 192.168.10.1
+
+   ikev2 profile set pr1 traffic-selector local ip-range 192.168.3.0 - 192.168.3.255 port-range 0 - 65535 protocol 0
+   ikev2 profile set pr1 traffic-selector remote ip-range 192.168.5.0 - 192.168.5.255 port-range 0 - 65535 protocol 0
+
+   create ipip tunnel src 192.168.10.2 dst 192.168.10.1
+   ikev2 profile set pr1 tunnel ipip0
+   ip route add 192.168.5.0/24 via 192.168.10.1 ipip0
+   set interface unnumbered ipip0 use host-ifresp
+
+Run initiator VPP:
+
+::
+
+   sudo /usr/bin/vpp unix { \
+         cli-listen /tmp/vpp_init.sock \
+         gid $(id -g) } \
+         api-segment { prefix vpp } \
+         plugins { plugin dpdk_plugin.so { disable } }
+
+Configure initiator:
+
+::
+
+   create host-interface name ifinit
+   set interface ip addr host-ifinit 192.168.10.1/24
+   set interface state host-ifinit up
+
+   create host-interface name client
+   set interface ip addr host-client 192.168.5.1/24
+   set interface state host-client up
+
+   ikev2 profile add pr1
+   ikev2 profile set pr1 auth shared-key-mic string Vpp123
+   ikev2 profile set pr1 id local ipv4 192.168.10.1
+   ikev2 profile set pr1 id remote ipv4 192.168.10.2
+
+   ikev2 profile set pr1 traffic-selector remote ip-range 192.168.3.0 - 192.168.3.255 port-range 0 - 65535 protocol 0
+   ikev2 profile set pr1 traffic-selector local ip-range 192.168.5.0 - 192.168.5.255 port-range 0 - 65535 protocol 0
+
+   ikev2 profile set pr1 responder host-ifinit 192.168.10.2
+   ikev2 profile set pr1 ike-crypto-alg aes-gcm-16 256 ike-dh modp-2048
+   ikev2 profile set pr1 esp-crypto-alg aes-gcm-16 256
+
+   create ipip tunnel src 192.168.10.1 dst 192.168.10.2
+   ikev2 profile set pr1 tunnel ipip0
+   ip route add 192.168.3.0/24 via 192.168.10.2 ipip0
+   set interface unnumbered ipip0 use host-ifinit
+
+Initiate the IKEv2 connection:
+
+::
+
+   vpp# ikev2 initiate sa-init pr1
+
+Responder’s and initiator’s private networks are now connected with
+IPSEC tunnel:
+
+::
+
+   $ sudo ip netns exec clientns ping 192.168.3.1
+   PING 192.168.3.1 (192.168.3.1) 56(84) bytes of data.
+   64 bytes from 192.168.3.1: icmp_seq=1 ttl=63 time=1.64 ms
+   64 bytes from 192.168.3.1: icmp_seq=2 ttl=63 time=7.24 ms
diff --git a/docs/usecases/ikev2/index.rst b/docs/usecases/ikev2/index.rst
new file mode 100644
index 00000000000..c9829b41908
--- /dev/null
+++ b/docs/usecases/ikev2/index.rst
@@ -0,0 +1,14 @@
+.. _ikev2:
+
+IKEv2 with VPP
+==============
+
+This sections describes some of the ways to establish IKEv2 connection
+between two VPP instances or VPP and strongSwan. It covers scenarios in
+which VPP is the IKEv2 responder (and strongSwan initiator) and vice versa.
+
+.. toctree::
+
+    vpp_resp_sswan_init
+    vpp_init_sswan_resp
+    2_vpp
diff --git a/docs/usecases/ikev2/vpp_init_sswan_resp.rst b/docs/usecases/ikev2/vpp_init_sswan_resp.rst
new file mode 100644
index 00000000000..93862185773
--- /dev/null
+++ b/docs/usecases/ikev2/vpp_init_sswan_resp.rst
@@ -0,0 +1,202 @@
+VPP as IKEv2 initiator and strongSwan as responder
+==================================================
+
+Prerequisites
+-------------
+
+To make the examples easier to configure ``docker`` it is required to
+pull strongSwan docker image. The networking is done using Linux’ veth
+interfaces and namespaces.
+
+Setup
+-----
+
+First a topology:
+
+::
+
+   192.168.3.2                      192.168.5.2
+        +                           loopback
+        |                                 +
+   +----+----+ 192.168.10.2         +-----+----+
+   |  VPP    |                      |strongSwan|
+   |initiator+----------------------+responder |
+   +---------+                      +----------+
+                        192.168.10.1
+
+Create veth interfaces and namespaces and configure them:
+
+::
+
+   sudo ip link add gw type veth peer name swanif
+   sudo ip link set dev gw up
+
+   sudo ip netns add ns
+   sudo ip link add veth_priv type veth peer name priv
+   sudo ip link set dev priv up
+   sudo ip link set dev veth_priv up netns ns
+
+   sudo ip netns exec ns \
+     bash -c "
+       ip link set dev lo up
+       ip addr add 192.168.3.2/24 dev veth_priv
+       ip route add 192.168.5.0/24 via 192.168.3.1"
+
+Create directory with strongswan configs that will be mounted to the
+docker container
+
+::
+
+   mkdir /tmp/sswan
+
+Create the ``ipsec.conf`` file in the ``/tmp/sswan`` directory with
+following content:
+
+::
+
+   config setup
+     strictcrlpolicy=no
+
+   conn initiator
+     mobike=no
+     auto=add
+     type=tunnel
+     keyexchange=ikev2
+     ike=aes256gcm16-prfsha256-modp2048!
+     esp=aes256gcm16-esn!
+
+   # local:
+     leftauth=psk
+     leftid=@sswan.vpn.example.com
+     leftsubnet=192.168.5.0/24
+
+   # remote: (gateway)
+     rightid=@roadwarrior.vpp
+     right=192.168.10.2
+     rightauth=psk
+     rightsubnet=192.168.3.0/24
+
+``/tmp/sswan/ipsec.secrets``
+
+::
+
+   : PSK 'Vpp123'
+
+``/tmp/sswan/strongswan.conf``
+
+::
+
+   charon {
+     load_modular = yes
+     plugins {
+       include strongswan.d/charon/*.conf
+     }
+     filelog {
+       /tmp/charon.log {
+         time_format = %b %e %T
+         ike_name = yes
+         append = no
+         default = 2
+         flush_line = yes
+       }
+     }
+   }
+   include strongswan.d/*.conf
+
+Start docker container with strongSwan:
+
+::
+
+    docker run --name sswan -d --privileged --rm --net=none \
+     -v /tmp/sswan:/conf -v /tmp/sswan:/etc/ipsec.d philplckthun/strongswan
+
+Finish configuration of initiator’s private network:
+
+::
+
+   pid=$(docker inspect --format "{{.State.Pid}}" sswan)
+   sudo ip link set netns $pid dev swanif
+
+   sudo nsenter -t $pid -n ip addr add 192.168.10.1/24 dev swanif
+   sudo nsenter -t $pid -n ip link set dev swanif up
+
+   sudo nsenter -t $pid -n ip addr add 192.168.5.2/32 dev lo
+   sudo nsenter -t $pid -n ip link set dev lo up
+
+Start VPP …
+
+::
+
+   sudo /usr/bin/vpp unix { \
+         cli-listen /tmp/vpp.sock \
+         gid $(id -g) } \
+         api-segment { prefix vpp } \
+         plugins { plugin dpdk_plugin.so { disable } }
+
+… and configure it:
+
+::
+
+   create host-interface name gw
+   set interface ip addr host-gw 192.168.10.2/24
+   set interface state host-gw up
+
+   create host-interface name priv
+   set interface ip addr host-priv 192.168.3.1/24
+   set interface state host-priv up
+
+   ikev2 profile add pr1
+   ikev2 profile set pr1 auth shared-key-mic string Vpp123
+   ikev2 profile set pr1 id local fqdn roadwarrior.vpp
+   ikev2 profile set pr1 id remote fqdn sswan.vpn.example.com
+
+   ikev2 profile set pr1 traffic-selector local ip-range 192.168.3.0 - 192.168.3.255 port-range 0 - 65535 protocol 0
+   ikev2 profile set pr1 traffic-selector remote ip-range 192.168.5.0 - 192.168.5.255 port-range 0 - 65535 protocol 0
+
+   ikev2 profile set pr1 responder host-gw 192.168.10.1
+   ikev2 profile set pr1 ike-crypto-alg aes-gcm-16 256 ike-dh modp-2048
+   ikev2 profile set pr1 esp-crypto-alg aes-gcm-16 256
+
+   create ipip tunnel src 192.168.10.2 dst 192.168.10.1
+   ikev2 profile set pr1 tunnel ipip0
+   ip route add 192.168.5.0/24 via 192.168.10.1 ipip0
+   set interface unnumbered ipip0 use host-gw
+
+Initiate the IKEv2 connection:
+
+::
+
+   vpp# ikev2 initiate sa-init pr1
+
+::
+
+   vpp# show ikev2 sa details
+    iip 192.168.10.2 ispi f717b0cbd17e27c3 rip 192.168.10.1 rspi e9b7af7fc9b13361
+    encr:aes-gcm-16 prf:hmac-sha2-256  dh-group:modp-2048
+    nonce i:eb0354613b268c6372061bbdaab13deca37c8a625b1f65c073d25df2ecfe672e
+          r:70e1248ac09943047064f6a2135fa2a424778ba03038ab9c4c2af8aba179ed84
+    SK_d    96bd4feb59be2edf1930a12a3a5d22e30195ee9f56ea203c5fb6cba5dd2bb80f
+    SK_e  i:00000000: 5b75b9d808c8467fd00a0923c06efee2a4eb1d033c57532e05f9316ed9c56fe9
+            00000020: c4db9114
+          r:00000000: 95121b63372d20b83558dc3e209b9affef042816cf071c86a53543677b40c15b
+            00000020: f169ab67
+    SK_p  i:fb40d1114c347ddc3228ba004d4759d58f9c1ae6f1746833f908d39444ef92b1
+          r:aa049828240cb242e1d5aa625cd5914dc8f8e980a74de8e06883623d19384902
+    identifier (i) id-type fqdn data roadwarrior.vpp
+    identifier (r) id-type fqdn data sswan.vpn.example.com
+      child sa 0:encr:aes-gcm-16  esn:yes
+       spi(i) 9dffd57a spi(r) c4e0ef53
+       SK_e  i:290c681694f130b33d511335dd257e78721635b7e8aa87930dd77bb1d6dd3f42
+             r:0a09fa18cf1cf65c6324df02b46dcc998b84e5397cf911b63e0c096053946c2e
+       traffic selectors (i):0 type 7 protocol_id 0 addr 192.168.3.0 - 192.168.3.255 port 0 - 65535
+       traffic selectors (r):0 type 7 protocol_id 0 addr 192.168.5.0 - 192.168.5.255 port 0 - 65535
+
+Now we can generate some traffic between responder’s and initiator’s
+private networks and see it works.
+
+::
+
+   $ sudo ip netns exec ns ping 192.168.5.2
+   PING 192.168.5.2 (192.168.5.2) 56(84) bytes of data.
+   64 bytes from 192.168.5.2: icmp_seq=1 ttl=63 time=0.450 ms
+   64 bytes from 192.168.5.2: icmp_seq=2 ttl=63 time=0.630 ms
diff --git a/docs/usecases/ikev2/vpp_resp_sswan_init.rst b/docs/usecases/ikev2/vpp_resp_sswan_init.rst
new file mode 100644
index 00000000000..9f3c7e7cbaf
--- /dev/null
+++ b/docs/usecases/ikev2/vpp_resp_sswan_init.rst
@@ -0,0 +1,203 @@
+VPP as IKEv2 responder and strongSwan as initiator
+==================================================
+
+Prerequisites
+-------------
+
+To make the examples easier to configure ``docker`` it is required to
+pull strongSwan docker image. The networking is done using Linux’ veth
+interfaces and namespaces.
+
+Setup
+-----
+
+First a topology:
+
+::
+
+   192.168.3.2                      192.168.5.2
+        +                           loopback
+        |                                 +
+   +----+----+ 192.168.10.2         +-----+----+
+   |  VPP    |                      |initiator |
+   |responder+----------------------+strongSwan|
+   +---------+                      +----------+
+                        192.168.10.1
+
+Create veth interfaces and namespaces and configure them:
+
+::
+
+   sudo ip link add gw type veth peer name swanif
+   sudo ip link set dev gw up
+
+   sudo ip netns add ns
+   sudo ip link add veth_priv type veth peer name priv
+   sudo ip link set dev priv up
+   sudo ip link set dev veth_priv up netns ns
+
+   sudo ip netns exec ns \
+     bash -c "
+       ip link set dev lo up
+       ip addr add 192.168.3.2/24 dev veth_priv
+       ip route add 192.168.5.0/24 via 192.168.3.1"
+
+Create directory with strongswan configs that will be mounted to the
+docker container
+
+::
+
+   mkdir /tmp/sswan
+
+Create the ``ipsec.conf`` file in the ``/tmp/sswan`` directory with
+following content:
+
+::
+
+   config setup
+    strictcrlpolicy=no
+
+   conn initiator
+    mobike=no
+    auto=add
+    type=tunnel
+    keyexchange=ikev2
+    ike=aes256gcm16-prfsha256-modp2048!
+    esp=aes256gcm16-esn!
+
+    # local:
+    leftauth=psk
+    leftid=@roadwarrior.vpn.example.com
+    leftsubnet=192.168.5.0/24
+
+    # remote: (vpp gateway)
+    rightid=@vpp.home
+    right=192.168.10.2
+    rightauth=psk
+    rightsubnet=192.168.3.0/24
+
+``/tmp/sswan/ipsec.secrets``
+
+::
+
+   : PSK 'Vpp123'
+
+``/tmp/sswan/strongswan.conf``
+
+::
+
+   charon {
+     load_modular = yes
+     plugins {
+       include strongswan.d/charon/*.conf
+     }
+     filelog {
+       /tmp/charon.log {
+         time_format = %b %e %T
+         ike_name = yes
+         append = no
+         default = 2
+         flush_line = yes
+       }
+     }
+   }
+   include strongswan.d/*.conf
+
+Start docker container with strongSwan:
+
+::
+
+    docker run --name sswan -d --privileged --rm --net=none \
+     -v /tmp/sswan:/conf -v /tmp/sswan:/etc/ipsec.d philplckthun/strongswan
+
+Finish configuration of initiator’s private network:
+
+::
+
+   pid=$(docker inspect --format "{{.State.Pid}}" sswan)
+   sudo ip link set netns $pid dev swanif
+
+   sudo nsenter -t $pid -n ip addr add 192.168.10.1/24 dev swanif
+   sudo nsenter -t $pid -n ip link set dev swanif up
+
+   sudo nsenter -t $pid -n ip addr add 192.168.5.2/32 dev lo
+   sudo nsenter -t $pid -n ip link set dev lo up
+
+Start VPP …
+
+::
+
+   sudo /usr/bin/vpp unix { \
+         cli-listen /tmp/vpp.sock \
+         gid $(id -g) } \
+         api-segment { prefix vpp } \
+         plugins { plugin dpdk_plugin.so { disable } }
+
+… and configure it:
+
+::
+
+   create host-interface name gw
+   set interface ip addr host-gw 192.168.10.2/24
+   set interface state host-gw up
+
+   create host-interface name priv
+   set interface ip addr host-priv 192.168.3.1/24
+   set interface state host-priv up
+
+   ikev2 profile add pr1
+   ikev2 profile set pr1 auth shared-key-mic string Vpp123
+   ikev2 profile set pr1 id local fqdn vpp.home
+   ikev2 profile set pr1 id remote fqdn roadwarrior.vpn.example.com
+
+   ikev2 profile set pr1 traffic-selector local ip-range 192.168.3.0 - 192.168.3.255 port-range 0 - 65535 protocol 0
+   ikev2 profile set pr1 traffic-selector remote ip-range 192.168.5.0 - 192.168.5.255 port-range 0 - 65535 protocol 0
+
+   create ipip tunnel src 192.168.10.2 dst 192.168.10.1
+   ikev2 profile set pr1 tunnel ipip0
+   ip route add 192.168.5.0/24 via 192.168.10.1 ipip0
+   set interface unnumbered ipip0 use host-gw
+
+Initiate the IKEv2 connection:
+
+::
+
+   $ sudo docker exec sswan ipsec up initiator
+
+   ...
+   CHILD_SA initiator{1} established with SPIs c320c95f_i 213932c2_o and TS 192.168.5.0/24 === 192.168.3.0/24
+   connection 'initiator' established successfully
+
+::
+
+   vpp# show ikev2 sa details
+
+   iip 192.168.10.1 ispi 7849021d9f655f1b rip 192.168.10.2 rspi 5a9ca7469a035205
+    encr:aes-gcm-16 prf:hmac-sha2-256  dh-group:modp-2048
+    nonce i:692ce8fd8f1c1934f63bfa2b167c4de2cff25640dffe938cdfe01a5d7f6820e6
+          r:3ed84a14ea8526063e5aa762312be225d33e866d7152b9ce23e50f0ededca9e3
+    SK_d    9a9b896ed6c35c78134fcd6e966c04868b6ecacf6d5088b4b2aee8b05d30fdda
+    SK_e  i:00000000: 1b1619788d8c812ca5916c07e635bda860f15293099f3bf43e8d88e52074b006
+            00000020: 72c8e3e3
+          r:00000000: 89165ceb2cef6a6b3319f437386292d9ef2e96d8bdb21eeb0cb0d3b92733de03
+            00000020: bbc29c50
+    SK_p  i:fe35fca30985ee75e7c8bc0d7bc04db7a0e1655e997c0f5974c31458826b6fef
+          r:0dd318662a96a25fcdf4998d8c6e4180c67c03586cf91dab26ed43aeda250272
+    identifier (i) id-type fqdn data roadwarrior.vpn.example.com
+    identifier (r) id-type fqdn data vpp.home
+      child sa 0:encr:aes-gcm-16  esn:yes
+       spi(i) c320c95f spi(r) 213932c2
+       SK_e  i:2a6c9eae9dbed202c0ae6ccc001621aba5bb0b01623d4de4d14fd27bd5185435
+             r:15e2913d39f809040ca40a02efd27da298b6de05f67bd8f10210da5e6ae606fb
+       traffic selectors (i):0 type 7 protocol_id 0 addr 192.168.5.0 - 192.168.5.255 port 0 - 65535
+       traffic selectors (r):0 type 7 protocol_id 0 addr 192.168.3.0 - 192.168.3.255 port 0 - 65535
+
+Now we can generate some traffic between responder’s and initiator’s
+private networks and see it works.
+
+::
+
+   $ sudo ip netns exec ns ping 192.168.5.2
+   PING 192.168.5.2 (192.168.5.2) 56(84) bytes of data.
+   64 bytes from 192.168.5.2: icmp_seq=1 ttl=63 time=1.02 ms
+   64 bytes from 192.168.5.2: icmp_seq=2 ttl=63 time=0.599 ms