X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=ceph%2Fsrc%2Fspdk%2Fdpdk%2Fdoc%2Fguides%2Fsample_app_ug%2Fipsec_secgw.rst;h=81c5d43606159a4cb62d29162f716eebfce2c6c1;hb=f67539c23b11f3b8a2ecaeeddf7a403ae1c442a8;hp=ac118c1a2184a5ac730cf38e22ba9b48691c5f57;hpb=9f95a23ce0ce15b5cd2b85dc8aaf3906fbf7f463;p=ceph.git diff --git a/ceph/src/spdk/dpdk/doc/guides/sample_app_ug/ipsec_secgw.rst b/ceph/src/spdk/dpdk/doc/guides/sample_app_ug/ipsec_secgw.rst index ac118c1a2..81c5d4360 100644 --- a/ceph/src/spdk/dpdk/doc/guides/sample_app_ug/ipsec_secgw.rst +++ b/ceph/src/spdk/dpdk/doc/guides/sample_app_ug/ipsec_secgw.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2016-2017 Intel Corporation. + Copyright (C) 2020 Marvell International Ltd. IPsec Security Gateway Sample Application ========================================= @@ -61,6 +62,44 @@ 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 ----------- @@ -69,7 +108,6 @@ 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 ------------------------- @@ -94,11 +132,19 @@ The application has a number of command line options:: ./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: @@ -111,9 +157,13 @@ 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. @@ -127,12 +177,42 @@ Where: * ``-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 @@ -144,22 +224,33 @@ Where: 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. @@ -173,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: @@ -201,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. @@ -387,7 +505,8 @@ The SA rule syntax is shown as follows: .. code-block:: console sa - + + where each options means: @@ -420,6 +539,7 @@ 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 @@ -475,6 +595,8 @@ where each options means: * 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 * @@ -486,11 +608,12 @@ where each options means: Must be followed by 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* ```` @@ -559,6 +682,38 @@ where each options means: * *port_id X* X is a valid device number in decimal + ```` + + * 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* + +```` + + * 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: @@ -589,6 +744,9 @@ 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 ^^^^^^^^^^^^^^^^^^^ @@ -712,6 +870,13 @@ Also the user can optionally setup: * ``CRYPTO_DEV``: crypto device to be used ('-w '). 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. @@ -754,17 +919,40 @@ SUT OS(TAP)--(plain)-->(TAP)psec-secgw(NIC1)--(IPsec)-->(NIC1)DUT OS 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 + +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 +* ``-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 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