.. SPDX-License-Identifier: BSD-3-Clause
Copyright(c) 2016-2017 Intel Corporation.
+ Copyright (C) 2020 Marvell International Ltd.
IPsec Security Gateway Sample Application
=========================================
* 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 AH mode.
* 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
-------------------------
./build/ipsec-secgw [EAL options] --
-p PORTMASK -P -u PORTMASK -j FRAMESIZE
-l -w REPLAY_WINOW_SIZE -e -a
- --config (port,queue,lcore)[,(port,queue,lcore]
+ -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
- -f CONFIG_FILE_PATH
+ --reassemble NUM
+ --mtu MTU
+ --frag-ttl FRAG_TTL_NS
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.
* ``-a``: enables Security Association sequence number atomic behavior
(available only with librte_ipsec code path).
-* ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues
- from which ports are mapped to which cores.
+* ``-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
-* ``--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.
+* ``--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 TX HW offload capabilities.
By default all HW TX offloads are enabled.
-* ``-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.
+* ``--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.
* 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:
**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.
.. code-block:: console
sa <dir> <spi> <cipher_algo> <cipher_key> <auth_algo> <auth_key>
- <mode> <src_ip> <dst_ip> <action_type> <port_id>
+ <mode> <src_ip> <dst_ip> <action_type> <port_id> <fallback>
+ <flow-direction> <port_id> <queue_id>
where each options means:
* *null*: NULL algorithm
* *aes-128-cbc*: AES-CBC 128-bit algorithm
+ * *aes-192-cbc*: AES-CBC 192-bit algorithm
* *aes-256-cbc*: AES-CBC 256-bit algorithm
* *aes-128-ctr*: AES-CTR 128-bit algorithm
* *3des-cbc*: 3DES-CBC 192-bit algorithm
* Available options:
* *aes-128-gcm*: AES-GCM 128-bit algorithm
+ * *aes-192-gcm*: AES-GCM 192-bit algorithm
+ * *aes-256-gcm*: AES-GCM 256-bit algorithm
* Syntax: *cipher_algo <your algorithm>*
Must be followed by <aead_algo> option
* Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
- The number of bytes should be as same as the specified AEAD algorithm
- key size.
+ Last 4 bytes of the provided key will be used as 'salt' and so, the
+ number of bytes should be same as the sum of specified AEAD algorithm
+ key size and salt size (4 bytes).
For example: *aead_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
- A1:B2:C3:D4*
+ A1:B2:C3:D4:A1:B2:C3:D4*
``<mode>``
* *port_id X* X is a valid device number in decimal
+ ``<fallback>``
+
+ * Action type for ingress IPsec packets that inline processor failed to
+ process. Only a combination of *inline-crypto-offload* as a primary
+ session and *lookaside-none* as a fall-back session is supported at the
+ moment.
+
+ If used in conjunction with IPsec window, its width needs be increased
+ due to different processing times of inline and lookaside modes which
+ results in packet reordering.
+
+ * Optional: Yes.
+
+ * Available options:
+
+ * *lookaside-none*: use automatically chosen cryptodev to process packets
+
+ * Syntax:
+
+ * *fallback lookaside-none*
+
+``<flow-direction>``
+
+ * Option for redirecting a specific inbound ipsec flow of a port to a specific
+ queue of that port.
+
+ * Optional: Yes.
+
+ * Available options:
+
+ * *port_id*: Port ID of the NIC for which the SA is configured.
+ * *queue_id*: Queue ID to which traffic should be redirected.
Example SA rules:
mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5 \
type inline-crypto-offload port_id 0
+ sa in 117 cipher_algo null auth_algo null mode ipv4-tunnel src 172.16.2.7 \
+ dst 172.16.1.7 flow-direction 0 2
+
Routing rule syntax
^^^^^^^^^^^^^^^^^^^
* ``CRYPTO_DEV``: crypto device to be used ('-w <pci-id>'). If none specified
appropriate vdevs will be created by the script
+Scripts can be used for multiple test scenarios. To check all available
+options run:
+
+.. code-block:: console
+
+ /bin/bash run_test.sh -h
+
Note that most of the tests require the appropriate crypto PMD/device to be
available.
It then tries to perform some data transfer using the scheme described above.
-usage
+Usage
~~~~~
-In the ipsec-secgw/test directory
+In the ipsec-secgw/test directory run
+
+/bin/bash run_test.sh <options> <ipsec_mode>
+
+Available options:
+
+* ``-4`` Perform tests with use of IPv4. One or both [-46] options needs to be
+ selected.
+
+* ``-6`` Perform tests with use of IPv6. One or both [-46] options needs to be
+ selected.
+
+* ``-m`` Add IPSec tunnel mixed IP version tests - outer IP version different
+ than inner. Inner IP version will match selected option [-46].
+
+* ``-i`` Run tests in inline mode. Regular tests will not be invoked.
+
+* ``-f`` Run tests for fallback mechanism. Regular tests will not be invoked.
+
+* ``-l`` Run tests in legacy mode only. It cannot be used with options [-fsc].
+ On default library mode is used.
-to run one test for IPv4 or IPv6
+* ``-s`` Run all tests with reassembly support. On default only tests for
+ fallback mechanism use reassembly support.
-/bin/bash linux_test(4|6).sh <ipsec_mode>
+* ``-c`` Run tests with use of cpu-crypto. For inline tests it will not be
+ applied. On default lookaside-none is used.
-to run all tests for IPv4 or IPv6
+* ``-p`` Perform packet validation tests. Option [-46] is not required.
-/bin/bash run_test.sh -4|-6
+* ``-h`` Show usage.
-For the list of available modes please refer to run_test.sh.
+If <ipsec_mode> is specified, only tests for that mode will be invoked. For the
+list of available modes please refer to run_test.sh.
\ No newline at end of file
projects / ceph.git / blobdiff