diff mbox series

[v4,9/9] doc: update ipsec-secgw guide and relelase notes

Message ID 1544805623-18150-10-git-send-email-konstantin.ananyev@intel.com (mailing list archive)
State Superseded, archived
Delegated to: Thomas Monjalon
Headers show
Series examples/ipsec-secgw: make app to use ipsec library | expand


Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation success Compilation OK

Commit Message

Konstantin Ananyev Dec. 14, 2018, 4:40 p.m. UTC
Update ipsec-secgw guide and relelase notes to reflect latest changes.

Signed-off-by: Bernard Iremonger <bernard.iremonger@intel.com>
Signed-off-by: Konstantin Ananyev <konstantin.ananyev@intel.com>
 doc/guides/rel_notes/release_19_02.rst   |  14 ++++
 doc/guides/sample_app_ug/ipsec_secgw.rst | 101 ++++++++++++++++++++++-
 2 files changed, 113 insertions(+), 2 deletions(-)
diff mbox series


diff --git a/doc/guides/rel_notes/release_19_02.rst b/doc/guides/rel_notes/release_19_02.rst
index e88289f73..021034c62 100644
--- a/doc/guides/rel_notes/release_19_02.rst
+++ b/doc/guides/rel_notes/release_19_02.rst
@@ -71,6 +71,20 @@  New Features
   See :doc:`../prog_guide/ipsec_lib` for more information.
+* **Updated the ipsec-secgw sample application.**
+    The ``ipsec-secgw`` sample application has been updated to use the new
+    ``librte_ipsec`` library also added in this release.
+    The original functionality of ipsec-secgw is retained, a new command line
+    parameter ``-l`` has  been added to ipsec-secgw to use the IPsec library,
+    instead of the existing IPsec code in the application.
+    The IPsec library does not support all the functionality of the existing
+    ipsec-secgw application, its is planned to add the outstanding functionality
+    in future releases.
+    See :doc:`../sample_app_ug/ipsec_secgw` for more information.
 Removed Items
diff --git a/doc/guides/sample_app_ug/ipsec_secgw.rst b/doc/guides/sample_app_ug/ipsec_secgw.rst
index 4869a011d..c159ddac7 100644
--- a/doc/guides/sample_app_ug/ipsec_secgw.rst
+++ b/doc/guides/sample_app_ug/ipsec_secgw.rst
@@ -76,7 +76,7 @@  Compiling the Application
 To compile the sample application see :doc:`compiling`.
-The application is located in the ``rpsec-secgw`` sub-directory.
+The application is located in the ``ipsec-secgw`` sub-directory.
 #. [Optional] Build the application for debugging:
    This option adds some extra flags, disables compiler optimizations and
@@ -112,6 +112,15 @@  Where:
     specified as FRAMESIZE. If an invalid value is provided as FRAMESIZE
     then the default value 9000 is used.
+*   ``-l``: enables code-path that uses librte_ipsec.
+*   ``-w REPLAY_WINOW_SIZE``: specifies the IPsec sequence number replay window
+    size for each Security Association.
+*   ``-e``: enables Security Association extended sequence number processing.
+*   ``-a``: enables Security Association sequence number atomic behaviour.
 *   ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues
     from which ports are mapped to which cores.
@@ -213,7 +222,7 @@  accordingly.
 Configuration File Syntax
 As mention in the overview, the Security Policies are ACL rules.
 The application parsers the rules specified in the configuration file and
@@ -559,6 +568,11 @@  Example SA rules:
     mode ipv4-tunnel src dst \
     type lookaside-protocol-offload port_id 4
+    sa in 35 aead_algo aes-128-gcm \
+    aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \
+    mode ipv4-tunnel src dst \
+    type inline-crypto-offload port_id 0
 Routing rule syntax
@@ -619,3 +633,86 @@  Example SP rules:
     rt ipv4 dst port 0
     rt ipv6 dst 1111:1111:1111:1111:1111:1111:1111:5555/116 port 0
+Test directory
+The test directory contains scripts for testing the various encryption
+The purpose of the scripts is to automate ipsec-secgw testing
+using another system running linux as a DUT.
+The user must setup the following environment variables:
+*   ``SGW_PATH``: path to the ipsec-secgw binary to test.
+*   ``REMOTE_HOST``: IP address/hostname of the DUT.
+*   ``REMOTE_IFACE``: interface name for the test-port on the DUT.
+*   ``ETH_DEV``: ethernet device to be used on the SUT by DPDK ('-w <pci-id>')
+Also the user can optionally setup:
+*   ``SGW_LCORE``: lcore to run ipsec-secgw on (default value is 0)
+*   ``CRYPTO_DEV``: crypto device to be used ('-w <pci-id>'). If none specified
+    appropriate vdevs will be created by the script
+Note that most of the tests require the appropriate crypto PMD/device to be
+Server configuration
+Two servers are required for the tests, SUT and DUT.
+Make sure the user from the SUT can ssh to the DUT without entering the password.
+To enable this feature keys must be setup on the DUT.
+``ssh-keygen`` will make a private & public key pair on the SUT.
+``ssh-copy-id`` <user name>@<target host name> on the SUT will copy the public
+key to the DUT. It will ask for credentials so that it can upload the public key.
+The SUT and DUT are connected through at least 2 NIC ports.
+One NIC port is expected to be managed by linux on both machines and will be
+used as a control path.
+The second NIC port (test-port) should be bound to DPDK on the SUT, and should
+be managed by linux on the DUT.
+The script starts ``ipsec-secgw`` with 2 NIC devices: ``test-port`` and
+``tap vdev``.
+It then configures the local tap interface and the remote interface and IPsec
+policies in the following way:
+Traffic going over the test-port in both directions has to be protected by IPsec.
+Traffic going over the TAP port in both directions does not have to be protected.
+DUT OS(NIC1)--(IPsec)-->(NIC1)ipsec-secgw(TAP)--(plain)-->(TAP)SUT OS
+SUT OS(TAP)--(plain)-->(TAP)psec-secgw(NIC1)--(IPsec)-->(NIC1)DUT OS
+It then tries to perform some data transfer using the scheme decribed above.
+In the ipsec-secgw/test directory
+to run one test for IPv4 or IPv6
+/bin/bash linux_test(4|6).sh <ipsec_mode>
+to run all tests for IPv4 or IPv6
+/bin/bash run_test.sh -4|-6
+For the list of available modes please refer to run_test.sh.