X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fsample_app_ug%2Fipsec_secgw.rst;h=81c5d43606159a4cb62d29162f716eebfce2c6c1;hb=9dbc4e21e752ca98e23205c3d1bac53e03e934b3;hp=358e7635f0e91cf409b245e894045860d779c194;hpb=ec17993a145ac18614b3a6e481574e0e47cd4b11;p=dpdk.git diff --git a/doc/guides/sample_app_ug/ipsec_secgw.rst b/doc/guides/sample_app_ug/ipsec_secgw.rst index 358e7635f0..81c5d43606 100644 --- a/doc/guides/sample_app_ug/ipsec_secgw.rst +++ b/doc/guides/sample_app_ug/ipsec_secgw.rst @@ -1,32 +1,6 @@ -.. BSD LICENSE - Copyright(c) 2016-2017 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2016-2017 Intel Corporation. + Copyright (C) 2020 Marvell International Ltd. IPsec Security Gateway Sample Application ========================================= @@ -52,8 +26,8 @@ The application classifies the ports as *Protected* and *Unprotected*. Thus, traffic received on an Unprotected or Protected port is consider Inbound or Outbound respectively. -The application also supports complete IPSec protocol offload to hardware -(Look aside crypto accelarator or using ethernet device). It also support +The application also supports complete IPsec protocol offload to hardware +(Look aside crypto accelerator or using ethernet device). It also support inline ipsec processing by the supported ethernet device during transmission. These modes can be selected during the SA creation configuration. @@ -61,6 +35,12 @@ In case of complete protocol offload, the processing of headers(ESP and outer IP header) is done by the hardware and the application does not need to add/remove them during outbound/inbound processing. +For inline offloaded outbound traffic, the application will not do the LPM +lookup for routing, as the port on which the packet has to be forwarded will be +part of the SA. Security parameters will be configured on that port only, and +sending the packet on other ports could result in unencrypted packets being +sent out. + The Path for IPsec Inbound traffic is: * Read packets from the port. @@ -82,37 +62,59 @@ The Path for the IPsec Outbound traffic is: * Routing. * Write packet to port. +The application supports two modes of operation: poll mode and event mode. + +* In the poll mode a core receives packets from statically configured list + of eth ports and eth ports' queues. + +* In the event mode a core receives packets as events. After packet processing + is done core submits them back as events to an event device. This enables + multicore scaling and HW assisted scheduling by making use of the event device + capabilities. The event mode configuration is predefined. All packets reaching + given eth port will arrive at the same event queue. All event queues are mapped + to all event ports. This allows all cores to receive traffic from all ports. + Since the underlying event device might have varying capabilities, the worker + threads can be drafted differently to maximize performance. For example, if an + event device - eth device pair has Tx internal port, then application can call + rte_event_eth_tx_adapter_enqueue() instead of regular rte_event_enqueue_burst(). + So a thread which assumes that the device pair has internal port will not be the + right solution for another pair. The infrastructure added for the event mode aims + to help application to have multiple worker threads by maximizing performance from + every type of event device without affecting existing paths/use cases. The worker + to be used will be determined by the operating conditions and the underlying device + capabilities. **Currently the application provides non-burst, internal port worker + threads and supports inline protocol only.** It also provides infrastructure for + non-internal port however does not define any worker threads. + +Additionally the event mode introduces two submodes of processing packets: + +* Driver submode: This submode has bare minimum changes in the application to support + IPsec. There are no lookups, no routing done in the application. And for inline + protocol use case, the worker thread resembles l2fwd worker thread as the IPsec + processing is done entirely in HW. This mode can be used to benchmark the raw + performance of the HW. The driver submode is selected with --single-sa option + (used also by poll mode). When --single-sa option is used in conjution with event + mode then index passed to --single-sa is ignored. + +* App submode: This submode has all the features currently implemented with the + application (non librte_ipsec path). All the lookups, routing follows existing + methods and report numbers that can be compared against regular poll mode + benchmark numbers. Constraints ----------- * No IPv6 options headers. * No AH mode. -* Supported algorithms: AES-CBC, AES-CTR, AES-GCM, HMAC-SHA1 and NULL. +* Supported algorithms: AES-CBC, AES-CTR, AES-GCM, 3DES-CBC, HMAC-SHA1 and NULL. * Each SA must be handle by a unique lcore (*1 RX queue per port*). -* No chained mbufs. - Compiling the Application ------------------------- -To compile the application: - -#. Go to the sample application directory:: - - export RTE_SDK=/path/to/rte_sdk - cd ${RTE_SDK}/examples/ipsec-secgw - -#. Set the target (a default target is used if not specified). For example:: - - - export RTE_TARGET=x86_64-native-linuxapp-gcc - - See the *DPDK Getting Started Guide* for possible RTE_TARGET values. +To compile the sample application see :doc:`compiling`. -#. Build the application:: - - make +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 @@ -129,9 +131,20 @@ The application has a number of command line options:: ./build/ipsec-secgw [EAL options] -- -p PORTMASK -P -u PORTMASK -j FRAMESIZE - --config (port,queue,lcore)[,(port,queue,lcore] - --single-sa SAIDX + -l -w REPLAY_WINOW_SIZE -e -a + -c SAD_CACHE_SIZE + -s NUMBER_OF_MBUFS_IN_PACKET_POOL -f CONFIG_FILE_PATH + --config (port,queue,lcore)[,(port,queue,lcore)] + --single-sa SAIDX + --cryptodev_mask MASK + --transfer-mode MODE + --event-schedule-type TYPE + --rxoffload MASK + --txoffload MASK + --reassemble NUM + --mtu MTU + --frag-ttl FRAG_TTL_NS Where: @@ -144,33 +157,100 @@ Where: * ``-u PORTMASK``: hexadecimal bitmask of unprotected ports -* ``-j FRAMESIZE``: *optional*. Enables jumbo frames with the maximum size - specified as FRAMESIZE. If an invalid value is provided as FRAMESIZE - then the default value 9000 is used. +* ``-j FRAMESIZE``: *optional*. data buffer size (in bytes), + in other words maximum data size for one segment. + Packets with length bigger then FRAMESIZE still can be received, + but will be segmented. + Default value: RTE_MBUF_DEFAULT_BUF_SIZE (2176) + Minimum value: RTE_MBUF_DEFAULT_BUF_SIZE (2176) + Maximum value: UINT16_MAX (65535). + +* ``-l``: enables code-path that uses librte_ipsec. -* ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues - from which ports are mapped to which cores. +* ``-w REPLAY_WINOW_SIZE``: specifies the IPsec sequence number replay window + size for each Security Association (available only with librte_ipsec + code path). -* ``--single-sa SAIDX``: use a single SA for outbound traffic, bypassing the SP - on both Inbound and Outbound. This option is meant for debugging/performance - purposes. +* ``-e``: enables Security Association extended sequence number processing + (available only with librte_ipsec code path). + +* ``-a``: enables Security Association sequence number atomic behavior + (available only with librte_ipsec code path). + +* ``-c``: specifies the SAD cache size. Stores the most recent SA in a per + lcore cache. Cache represents flat array containing SA's indexed by SPI. + Zero value disables cache. + Default value: 128. + +* ``-s``: sets number of mbufs in packet pool, if not provided number of mbufs + will be calculated based on number of cores, eth ports and crypto queues. * ``-f CONFIG_FILE_PATH``: the full path of text-based file containing all configuration items for running the application (See Configuration file syntax section below). ``-f CONFIG_FILE_PATH`` **must** be specified. **ONLY** the UNIX format configuration file is accepted. +* ``--config (port,queue,lcore)[,(port,queue,lcore)]``: in poll mode determines + which queues from which ports are mapped to which cores. In event mode this + option is not used as packets are dynamically scheduled to cores by HW. + +* ``--single-sa SAIDX``: in poll mode use a single SA for outbound traffic, + bypassing the SP on both Inbound and Outbound. This option is meant for + debugging/performance purposes. In event mode selects driver submode, SA index + value is ignored. + +* ``--cryptodev_mask MASK``: hexadecimal bitmask of the crypto devices + to configure. + +* ``--transfer-mode MODE``: sets operating mode of the application + "poll" : packet transfer via polling (default) + "event" : Packet transfer via event device + +* ``--event-schedule-type TYPE``: queue schedule type, applies only when + --transfer-mode is set to event. + "ordered" : Ordered (default) + "atomic" : Atomic + "parallel" : Parallel + When --event-schedule-type is set as RTE_SCHED_TYPE_ORDERED/ATOMIC, event + device will ensure the ordering. Ordering will be lost when tried in PARALLEL. + +* ``--rxoffload MASK``: RX HW offload capabilities to enable/use on this port + (bitmask of DEV_RX_OFFLOAD_* values). It is an optional parameter and + allows user to disable some of the RX HW offload capabilities. + By default all HW RX offloads are enabled. + +* ``--txoffload MASK``: TX HW offload capabilities to enable/use on this port + (bitmask of DEV_TX_OFFLOAD_* values). It is an optional parameter and + allows user to disable some of the TX HW offload capabilities. + By default all HW TX offloads are enabled. + +* ``--reassemble NUM``: max number of entries in reassemble fragment table. + Zero value disables reassembly functionality. + Default value: 0. + +* ``--mtu MTU``: MTU value (in bytes) on all attached ethernet ports. + Outgoing packets with length bigger then MTU will be fragmented. + Incoming packets with length bigger then MTU will be discarded. + Default value: 1500. + +* ``--frag-ttl FRAG_TTL_NS``: fragment lifetime (in nanoseconds). + If packet is not reassembled within this time, received fragments + will be discarded. Fragment lifetime should be decreased when + there is a high fragmented traffic loss in high bandwidth networks. + Should be lower for low number of reassembly buckets. + Valid values: from 1 ns to 10 s. Default value: 10000000 (10 s). + The mapping of lcores to port/queues is similar to other l3fwd applications. -For example, given the following command line:: +For example, given the following command line to run application in poll mode:: ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \ - --vdev "crypto_null" -- -p 0xf -P -u 0x3 \ + --vdev "crypto_null" -- -p 0xf -P -u 0x3 \ --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \ - -f /path/to/config_file \ + -f /path/to/config_file --transfer-mode poll \ -where each options means: +where each option means: * The ``-l`` option enables cores 20 and 21. @@ -184,7 +264,7 @@ where each options means: * The ``-P`` option enables promiscuous mode. -* The ``-u`` option sets ports 1 and 2 as unprotected, leaving 2 and 3 as protected. +* The ``-u`` option sets ports 0 and 1 as unprotected, leaving 2 and 3 as protected. * The ``--config`` option enables one queue per port with the following mapping: @@ -212,6 +292,33 @@ where each options means: **note** the parser only accepts UNIX format text file. Other formats such as DOS/MAC format will cause a parse error. +* The ``--transfer-mode`` option selects poll mode for processing packets. + +Similarly for example, given the following command line to run application in +event app mode:: + + ./build/ipsec-secgw -c 0x3 -- -P -p 0x3 -u 0x1 \ + -f /path/to/config_file --transfer-mode event \ + --event-schedule-type parallel \ + +where each option means: + +* The ``-c`` option selects cores 0 and 1 to run on. + +* The ``-P`` option enables promiscuous mode. + +* The ``-p`` option enables ports (detected) 0 and 1. + +* The ``-u`` option sets ports 0 as unprotected, leaving 1 as protected. + +* The ``-f /path/to/config_file`` option has the same behavior as in poll + mode example. + +* The ``--transfer-mode`` option selects event mode for processing packets. + +* The ``--event-schedule-type`` option selects parallel ordering of event queues. + + Refer to the *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options. @@ -241,7 +348,7 @@ Configurations -------------- The following sections provide the syntax of configurations to initialize -your SP, SA and Routing tables. +your SP, SA, Routing and Neighbour tables. Configurations shall be specified in the configuration file to be passed to the application. The file is then parsed by the application. The successful parsing will result in the appropriate rules being applied to the tables @@ -249,7 +356,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 @@ -262,8 +369,8 @@ General rule syntax The parse treats one line in the configuration file as one configuration item (unless the line concatenation symbol exists). Every configuration -item shall follow the syntax of either SP, SA, or Routing rules specified -below. +item shall follow the syntax of either SP, SA, Routing or Neighbour +rules specified below. The configuration parser supports the following special symbols: @@ -398,7 +505,8 @@ The SA rule syntax is shown as follows: .. code-block:: console sa