1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2016-2017 Intel Corporation. 3 4IPsec Security Gateway Sample Application 5========================================= 6 7The IPsec Security Gateway application is an example of a "real world" 8application using DPDK cryptodev framework. 9 10Overview 11-------- 12 13The application demonstrates the implementation of a Security Gateway 14(not IPsec compliant, see the Constraints section below) using DPDK based on RFC4301, 15RFC4303, RFC3602 and RFC2404. 16 17Internet Key Exchange (IKE) is not implemented, so only manual setting of 18Security Policies and Security Associations is supported. 19 20The Security Policies (SP) are implemented as ACL rules, the Security 21Associations (SA) are stored in a table and the routing is implemented 22using LPM. 23 24The application classifies the ports as *Protected* and *Unprotected*. 25Thus, traffic received on an Unprotected or Protected port is consider 26Inbound or Outbound respectively. 27 28The application also supports complete IPsec protocol offload to hardware 29(Look aside crypto accelerator or using ethernet device). It also support 30inline ipsec processing by the supported ethernet device during transmission. 31These modes can be selected during the SA creation configuration. 32 33In case of complete protocol offload, the processing of headers(ESP and outer 34IP header) is done by the hardware and the application does not need to 35add/remove them during outbound/inbound processing. 36 37For inline offloaded outbound traffic, the application will not do the LPM 38lookup for routing, as the port on which the packet has to be forwarded will be 39part of the SA. Security parameters will be configured on that port only, and 40sending the packet on other ports could result in unencrypted packets being 41sent out. 42 43The Path for IPsec Inbound traffic is: 44 45* Read packets from the port. 46* Classify packets between IPv4 and ESP. 47* Perform Inbound SA lookup for ESP packets based on their SPI. 48* Perform Verification/Decryption (Not needed in case of inline ipsec). 49* Remove ESP and outer IP header (Not needed in case of protocol offload). 50* Inbound SP check using ACL of decrypted packets and any other IPv4 packets. 51* Routing. 52* Write packet to port. 53 54The Path for the IPsec Outbound traffic is: 55 56* Read packets from the port. 57* Perform Outbound SP check using ACL of all IPv4 traffic. 58* Perform Outbound SA lookup for packets that need IPsec protection. 59* Add ESP and outer IP header (Not needed in case protocol offload). 60* Perform Encryption/Digest (Not needed in case of inline ipsec). 61* Routing. 62* Write packet to port. 63 64 65Constraints 66----------- 67 68* No IPv6 options headers. 69* No AH mode. 70* Supported algorithms: AES-CBC, AES-CTR, AES-GCM, 3DES-CBC, HMAC-SHA1 and NULL. 71* Each SA must be handle by a unique lcore (*1 RX queue per port*). 72 73Compiling the Application 74------------------------- 75 76To compile the sample application see :doc:`compiling`. 77 78The application is located in the ``ipsec-secgw`` sub-directory. 79 80#. [Optional] Build the application for debugging: 81 This option adds some extra flags, disables compiler optimizations and 82 is verbose:: 83 84 make DEBUG=1 85 86 87Running the Application 88----------------------- 89 90The application has a number of command line options:: 91 92 93 ./build/ipsec-secgw [EAL options] -- 94 -p PORTMASK -P -u PORTMASK -j FRAMESIZE 95 -l -w REPLAY_WINOW_SIZE -e -a 96 -c SAD_CACHE_SIZE 97 --config (port,queue,lcore)[,(port,queue,lcore] 98 --single-sa SAIDX 99 --rxoffload MASK 100 --txoffload MASK 101 --mtu MTU 102 --reassemble NUM 103 -f CONFIG_FILE_PATH 104 105Where: 106 107* ``-p PORTMASK``: Hexadecimal bitmask of ports to configure. 108 109* ``-P``: *optional*. Sets all ports to promiscuous mode so that packets are 110 accepted regardless of the packet's Ethernet MAC destination address. 111 Without this option, only packets with the Ethernet MAC destination address 112 set to the Ethernet address of the port are accepted (default is enabled). 113 114* ``-u PORTMASK``: hexadecimal bitmask of unprotected ports 115 116* ``-j FRAMESIZE``: *optional*. data buffer size (in bytes), 117 in other words maximum data size for one segment. 118 Packets with length bigger then FRAMESIZE still can be received, 119 but will be segmented. 120 Default value: RTE_MBUF_DEFAULT_BUF_SIZE (2176) 121 Minimum value: RTE_MBUF_DEFAULT_BUF_SIZE (2176) 122 Maximum value: UINT16_MAX (65535). 123 124* ``-l``: enables code-path that uses librte_ipsec. 125 126* ``-w REPLAY_WINOW_SIZE``: specifies the IPsec sequence number replay window 127 size for each Security Association (available only with librte_ipsec 128 code path). 129 130* ``-e``: enables Security Association extended sequence number processing 131 (available only with librte_ipsec code path). 132 133* ``-a``: enables Security Association sequence number atomic behavior 134 (available only with librte_ipsec code path). 135 136* ``-c``: specifies the SAD cache size. Stores the most recent SA in a per 137 lcore cache. Cache represents flat array containing SA's indexed by SPI. 138 Zero value disables cache. 139 Default value: 128. 140 141* ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues 142 from which ports are mapped to which cores. 143 144* ``--single-sa SAIDX``: use a single SA for outbound traffic, bypassing the SP 145 on both Inbound and Outbound. This option is meant for debugging/performance 146 purposes. 147 148* ``--rxoffload MASK``: RX HW offload capabilities to enable/use on this port 149 (bitmask of DEV_RX_OFFLOAD_* values). It is an optional parameter and 150 allows user to disable some of the RX HW offload capabilities. 151 By default all HW RX offloads are enabled. 152 153* ``--txoffload MASK``: TX HW offload capabilities to enable/use on this port 154 (bitmask of DEV_TX_OFFLOAD_* values). It is an optional parameter and 155 allows user to disable some of the TX HW offload capabilities. 156 By default all HW TX offloads are enabled. 157 158* ``--mtu MTU``: MTU value (in bytes) on all attached ethernet ports. 159 Outgoing packets with length bigger then MTU will be fragmented. 160 Incoming packets with length bigger then MTU will be discarded. 161 Default value: 1500. 162 163* ``--frag-ttl FRAG_TTL_NS``: fragment lifetime (in nanoseconds). 164 If packet is not reassembled within this time, received fragments 165 will be discarded. Fragment lifetime should be decreased when 166 there is a high fragmented traffic loss in high bandwidth networks. 167 Should be lower for low number of reassembly buckets. 168 Valid values: from 1 ns to 10 s. Default value: 10000000 (10 s). 169 170* ``--reassemble NUM``: max number of entries in reassemble fragment table. 171 Zero value disables reassembly functionality. 172 Default value: 0. 173 174* ``-f CONFIG_FILE_PATH``: the full path of text-based file containing all 175 configuration items for running the application (See Configuration file 176 syntax section below). ``-f CONFIG_FILE_PATH`` **must** be specified. 177 **ONLY** the UNIX format configuration file is accepted. 178 179 180The mapping of lcores to port/queues is similar to other l3fwd applications. 181 182For example, given the following command line:: 183 184 ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \ 185 --vdev "crypto_null" -- -p 0xf -P -u 0x3 \ 186 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \ 187 -f /path/to/config_file \ 188 189where each options means: 190 191* The ``-l`` option enables cores 20 and 21. 192 193* The ``-n`` option sets memory 4 channels. 194 195* The ``--socket-mem`` to use 2GB on socket 1. 196 197* The ``--vdev "crypto_null"`` option creates virtual NULL cryptodev PMD. 198 199* The ``-p`` option enables ports (detected) 0, 1, 2 and 3. 200 201* The ``-P`` option enables promiscuous mode. 202 203* The ``-u`` option sets ports 1 and 2 as unprotected, leaving 2 and 3 as protected. 204 205* The ``--config`` option enables one queue per port with the following mapping: 206 207 +----------+-----------+-----------+---------------------------------------+ 208 | **Port** | **Queue** | **lcore** | **Description** | 209 | | | | | 210 +----------+-----------+-----------+---------------------------------------+ 211 | 0 | 0 | 20 | Map queue 0 from port 0 to lcore 20. | 212 | | | | | 213 +----------+-----------+-----------+---------------------------------------+ 214 | 1 | 0 | 20 | Map queue 0 from port 1 to lcore 20. | 215 | | | | | 216 +----------+-----------+-----------+---------------------------------------+ 217 | 2 | 0 | 21 | Map queue 0 from port 2 to lcore 21. | 218 | | | | | 219 +----------+-----------+-----------+---------------------------------------+ 220 | 3 | 0 | 21 | Map queue 0 from port 3 to lcore 21. | 221 | | | | | 222 +----------+-----------+-----------+---------------------------------------+ 223 224* The ``-f /path/to/config_file`` option enables the application read and 225 parse the configuration file specified, and configures the application 226 with a given set of SP, SA and Routing entries accordingly. The syntax of 227 the configuration file will be explained below in more detail. Please 228 **note** the parser only accepts UNIX format text file. Other formats 229 such as DOS/MAC format will cause a parse error. 230 231Refer to the *DPDK Getting Started Guide* for general information on running 232applications and the Environment Abstraction Layer (EAL) options. 233 234The application would do a best effort to "map" crypto devices to cores, with 235hardware devices having priority. Basically, hardware devices if present would 236be assigned to a core before software ones. 237This means that if the application is using a single core and both hardware 238and software crypto devices are detected, hardware devices will be used. 239 240A way to achieve the case where you want to force the use of virtual crypto 241devices is to whitelist the Ethernet devices needed and therefore implicitly 242blacklisting all hardware crypto devices. 243 244For example, something like the following command line: 245 246.. code-block:: console 247 248 ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \ 249 -w 81:00.0 -w 81:00.1 -w 81:00.2 -w 81:00.3 \ 250 --vdev "crypto_aesni_mb" --vdev "crypto_null" \ 251 -- \ 252 -p 0xf -P -u 0x3 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \ 253 -f sample.cfg 254 255 256Configurations 257-------------- 258 259The following sections provide the syntax of configurations to initialize 260your SP, SA, Routing and Neighbour tables. 261Configurations shall be specified in the configuration file to be passed to 262the application. The file is then parsed by the application. The successful 263parsing will result in the appropriate rules being applied to the tables 264accordingly. 265 266 267Configuration File Syntax 268~~~~~~~~~~~~~~~~~~~~~~~~~ 269 270As mention in the overview, the Security Policies are ACL rules. 271The application parsers the rules specified in the configuration file and 272passes them to the ACL table, and replicates them per socket in use. 273 274Following are the configuration file syntax. 275 276General rule syntax 277^^^^^^^^^^^^^^^^^^^ 278 279The parse treats one line in the configuration file as one configuration 280item (unless the line concatenation symbol exists). Every configuration 281item shall follow the syntax of either SP, SA, Routing or Neighbour 282rules specified below. 283 284The configuration parser supports the following special symbols: 285 286 * Comment symbol **#**. Any character from this symbol to the end of 287 line is treated as comment and will not be parsed. 288 289 * Line concatenation symbol **\\**. This symbol shall be placed in the end 290 of the line to be concatenated to the line below. Multiple lines' 291 concatenation is supported. 292 293 294SP rule syntax 295^^^^^^^^^^^^^^ 296 297The SP rule syntax is shown as follows: 298 299.. code-block:: console 300 301 sp <ip_ver> <dir> esp <action> <priority> <src_ip> <dst_ip> 302 <proto> <sport> <dport> 303 304 305where each options means: 306 307``<ip_ver>`` 308 309 * IP protocol version 310 311 * Optional: No 312 313 * Available options: 314 315 * *ipv4*: IP protocol version 4 316 * *ipv6*: IP protocol version 6 317 318``<dir>`` 319 320 * The traffic direction 321 322 * Optional: No 323 324 * Available options: 325 326 * *in*: inbound traffic 327 * *out*: outbound traffic 328 329``<action>`` 330 331 * IPsec action 332 333 * Optional: No 334 335 * Available options: 336 337 * *protect <SA_idx>*: the specified traffic is protected by SA rule 338 with id SA_idx 339 * *bypass*: the specified traffic traffic is bypassed 340 * *discard*: the specified traffic is discarded 341 342``<priority>`` 343 344 * Rule priority 345 346 * Optional: Yes, default priority 0 will be used 347 348 * Syntax: *pri <id>* 349 350``<src_ip>`` 351 352 * The source IP address and mask 353 354 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used 355 356 * Syntax: 357 358 * *src X.X.X.X/Y* for IPv4 359 * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 360 361``<dst_ip>`` 362 363 * The destination IP address and mask 364 365 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used 366 367 * Syntax: 368 369 * *dst X.X.X.X/Y* for IPv4 370 * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 371 372``<proto>`` 373 374 * The protocol start and end range 375 376 * Optional: yes, default range of 0 to 0 will be used 377 378 * Syntax: *proto X:Y* 379 380``<sport>`` 381 382 * The source port start and end range 383 384 * Optional: yes, default range of 0 to 0 will be used 385 386 * Syntax: *sport X:Y* 387 388``<dport>`` 389 390 * The destination port start and end range 391 392 * Optional: yes, default range of 0 to 0 will be used 393 394 * Syntax: *dport X:Y* 395 396Example SP rules: 397 398.. code-block:: console 399 400 sp ipv4 out esp protect 105 pri 1 dst 192.168.115.0/24 sport 0:65535 \ 401 dport 0:65535 402 403 sp ipv6 in esp bypass pri 1 dst 0000:0000:0000:0000:5555:5555:\ 404 0000:0000/96 sport 0:65535 dport 0:65535 405 406 407SA rule syntax 408^^^^^^^^^^^^^^ 409 410The successfully parsed SA rules will be stored in an array table. 411 412The SA rule syntax is shown as follows: 413 414.. code-block:: console 415 416 sa <dir> <spi> <cipher_algo> <cipher_key> <auth_algo> <auth_key> 417 <mode> <src_ip> <dst_ip> <action_type> <port_id> <fallback> 418 419where each options means: 420 421``<dir>`` 422 423 * The traffic direction 424 425 * Optional: No 426 427 * Available options: 428 429 * *in*: inbound traffic 430 * *out*: outbound traffic 431 432``<spi>`` 433 434 * The SPI number 435 436 * Optional: No 437 438 * Syntax: unsigned integer number 439 440``<cipher_algo>`` 441 442 * Cipher algorithm 443 444 * Optional: Yes, unless <aead_algo> is not used 445 446 * Available options: 447 448 * *null*: NULL algorithm 449 * *aes-128-cbc*: AES-CBC 128-bit algorithm 450 * *aes-256-cbc*: AES-CBC 256-bit algorithm 451 * *aes-128-ctr*: AES-CTR 128-bit algorithm 452 * *3des-cbc*: 3DES-CBC 192-bit algorithm 453 454 * Syntax: *cipher_algo <your algorithm>* 455 456``<cipher_key>`` 457 458 * Cipher key, NOT available when 'null' algorithm is used 459 460 * Optional: Yes, unless <aead_algo> is not used. 461 Must be followed by <cipher_algo> option 462 463 * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. 464 The number of bytes should be as same as the specified cipher algorithm 465 key size. 466 467 For example: *cipher_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: 468 A1:B2:C3:D4* 469 470``<auth_algo>`` 471 472 * Authentication algorithm 473 474 * Optional: Yes, unless <aead_algo> is not used 475 476 * Available options: 477 478 * *null*: NULL algorithm 479 * *sha1-hmac*: HMAC SHA1 algorithm 480 481``<auth_key>`` 482 483 * Authentication key, NOT available when 'null' or 'aes-128-gcm' algorithm 484 is used. 485 486 * Optional: Yes, unless <aead_algo> is not used. 487 Must be followed by <auth_algo> option 488 489 * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. 490 The number of bytes should be as same as the specified authentication 491 algorithm key size. 492 493 For example: *auth_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: 494 A1:B2:C3:D4* 495 496``<aead_algo>`` 497 498 * AEAD algorithm 499 500 * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used 501 502 * Available options: 503 504 * *aes-128-gcm*: AES-GCM 128-bit algorithm 505 506 * Syntax: *cipher_algo <your algorithm>* 507 508``<aead_key>`` 509 510 * Cipher key, NOT available when 'null' algorithm is used 511 512 * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used. 513 Must be followed by <aead_algo> option 514 515 * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. 516 The number of bytes should be as same as the specified AEAD algorithm 517 key size. 518 519 For example: *aead_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: 520 A1:B2:C3:D4* 521 522``<mode>`` 523 524 * The operation mode 525 526 * Optional: No 527 528 * Available options: 529 530 * *ipv4-tunnel*: Tunnel mode for IPv4 packets 531 * *ipv6-tunnel*: Tunnel mode for IPv6 packets 532 * *transport*: transport mode 533 534 * Syntax: mode XXX 535 536``<src_ip>`` 537 538 * The source IP address. This option is not available when 539 transport mode is used 540 541 * Optional: Yes, default address 0.0.0.0 will be used 542 543 * Syntax: 544 545 * *src X.X.X.X* for IPv4 546 * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6 547 548``<dst_ip>`` 549 550 * The destination IP address. This option is not available when 551 transport mode is used 552 553 * Optional: Yes, default address 0.0.0.0 will be used 554 555 * Syntax: 556 557 * *dst X.X.X.X* for IPv4 558 * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6 559 560``<type>`` 561 562 * Action type to specify the security action. This option specify 563 the SA to be performed with look aside protocol offload to HW 564 accelerator or protocol offload on ethernet device or inline 565 crypto processing on the ethernet device during transmission. 566 567 * Optional: Yes, default type *no-offload* 568 569 * Available options: 570 571 * *lookaside-protocol-offload*: look aside protocol offload to HW accelerator 572 * *inline-protocol-offload*: inline protocol offload on ethernet device 573 * *inline-crypto-offload*: inline crypto processing on ethernet device 574 * *no-offload*: no offloading to hardware 575 576 ``<port_id>`` 577 578 * Port/device ID of the ethernet/crypto accelerator for which the SA is 579 configured. For *inline-crypto-offload* and *inline-protocol-offload*, this 580 port will be used for routing. The routing table will not be referred in 581 this case. 582 583 * Optional: No, if *type* is not *no-offload* 584 585 * Syntax: 586 587 * *port_id X* X is a valid device number in decimal 588 589 ``<fallback>`` 590 591 * Action type for ingress IPsec packets that inline processor failed to 592 process. Only a combination of *inline-crypto-offload* as a primary 593 session and *lookaside-none* as a fall-back session is supported at the 594 moment. 595 596 If used in conjunction with IPsec window, its width needs be increased 597 due to different processing times of inline and lookaside modes which 598 results in packet reordering. 599 600 * Optional: Yes. 601 602 * Available options: 603 604 * *lookaside-none*: use automatically chosen cryptodev to process packets 605 606 * Syntax: 607 608 * *fallback lookaside-none* 609 610Example SA rules: 611 612.. code-block:: console 613 614 sa out 5 cipher_algo null auth_algo null mode ipv4-tunnel \ 615 src 172.16.1.5 dst 172.16.2.5 616 617 sa out 25 cipher_algo aes-128-cbc \ 618 cipher_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \ 619 auth_algo sha1-hmac \ 620 auth_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \ 621 mode ipv6-tunnel \ 622 src 1111:1111:1111:1111:1111:1111:1111:5555 \ 623 dst 2222:2222:2222:2222:2222:2222:2222:5555 624 625 sa in 105 aead_algo aes-128-gcm \ 626 aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \ 627 mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5 628 629 sa out 5 cipher_algo aes-128-cbc cipher_key 0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0 \ 630 auth_algo sha1-hmac auth_key 0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0 \ 631 mode ipv4-tunnel src 172.16.1.5 dst 172.16.2.5 \ 632 type lookaside-protocol-offload port_id 4 633 634 sa in 35 aead_algo aes-128-gcm \ 635 aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \ 636 mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5 \ 637 type inline-crypto-offload port_id 0 638 639Routing rule syntax 640^^^^^^^^^^^^^^^^^^^ 641 642The Routing rule syntax is shown as follows: 643 644.. code-block:: console 645 646 rt <ip_ver> <src_ip> <dst_ip> <port> 647 648 649where each options means: 650 651``<ip_ver>`` 652 653 * IP protocol version 654 655 * Optional: No 656 657 * Available options: 658 659 * *ipv4*: IP protocol version 4 660 * *ipv6*: IP protocol version 6 661 662``<src_ip>`` 663 664 * The source IP address and mask 665 666 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used 667 668 * Syntax: 669 670 * *src X.X.X.X/Y* for IPv4 671 * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 672 673``<dst_ip>`` 674 675 * The destination IP address and mask 676 677 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used 678 679 * Syntax: 680 681 * *dst X.X.X.X/Y* for IPv4 682 * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 683 684``<port>`` 685 686 * The traffic output port id 687 688 * Optional: yes, default output port 0 will be used 689 690 * Syntax: *port X* 691 692Example SP rules: 693 694.. code-block:: console 695 696 rt ipv4 dst 172.16.1.5/32 port 0 697 698 rt ipv6 dst 1111:1111:1111:1111:1111:1111:1111:5555/116 port 0 699 700Neighbour rule syntax 701^^^^^^^^^^^^^^^^^^^^^ 702 703The Neighbour rule syntax is shown as follows: 704 705.. code-block:: console 706 707 neigh <port> <dst_mac> 708 709 710where each options means: 711 712``<port>`` 713 714 * The output port id 715 716 * Optional: No 717 718 * Syntax: *port X* 719 720``<dst_mac>`` 721 722 * The destination ethernet address to use for that port 723 724 * Optional: No 725 726 * Syntax: 727 728 * XX:XX:XX:XX:XX:XX 729 730Example Neighbour rules: 731 732.. code-block:: console 733 734 neigh port 0 DE:AD:BE:EF:01:02 735 736Test directory 737-------------- 738 739The test directory contains scripts for testing the various encryption 740algorithms. 741 742The purpose of the scripts is to automate ipsec-secgw testing 743using another system running linux as a DUT. 744 745The user must setup the following environment variables: 746 747* ``SGW_PATH``: path to the ipsec-secgw binary to test. 748 749* ``REMOTE_HOST``: IP address/hostname of the DUT. 750 751* ``REMOTE_IFACE``: interface name for the test-port on the DUT. 752 753* ``ETH_DEV``: ethernet device to be used on the SUT by DPDK ('-w <pci-id>') 754 755Also the user can optionally setup: 756 757* ``SGW_LCORE``: lcore to run ipsec-secgw on (default value is 0) 758 759* ``CRYPTO_DEV``: crypto device to be used ('-w <pci-id>'). If none specified 760 appropriate vdevs will be created by the script 761 762* ``MULTI_SEG_TEST``: ipsec-secgw option to enable reassembly support and 763 specify size of reassembly table (e.g. 764 ``MULTI_SEG_TEST='--reassemble 128'``). This option must be set for 765 fallback session tests. 766 767Note that most of the tests require the appropriate crypto PMD/device to be 768available. 769 770Server configuration 771~~~~~~~~~~~~~~~~~~~~ 772 773Two servers are required for the tests, SUT and DUT. 774 775Make sure the user from the SUT can ssh to the DUT without entering the password. 776To enable this feature keys must be setup on the DUT. 777 778``ssh-keygen`` will make a private & public key pair on the SUT. 779 780``ssh-copy-id`` <user name>@<target host name> on the SUT will copy the public 781key to the DUT. It will ask for credentials so that it can upload the public key. 782 783The SUT and DUT are connected through at least 2 NIC ports. 784 785One NIC port is expected to be managed by linux on both machines and will be 786used as a control path. 787 788The second NIC port (test-port) should be bound to DPDK on the SUT, and should 789be managed by linux on the DUT. 790 791The script starts ``ipsec-secgw`` with 2 NIC devices: ``test-port`` and 792``tap vdev``. 793 794It then configures the local tap interface and the remote interface and IPsec 795policies in the following way: 796 797Traffic going over the test-port in both directions has to be protected by IPsec. 798 799Traffic going over the TAP port in both directions does not have to be protected. 800 801i.e: 802 803DUT OS(NIC1)--(IPsec)-->(NIC1)ipsec-secgw(TAP)--(plain)-->(TAP)SUT OS 804 805SUT OS(TAP)--(plain)-->(TAP)psec-secgw(NIC1)--(IPsec)-->(NIC1)DUT OS 806 807It then tries to perform some data transfer using the scheme described above. 808 809usage 810~~~~~ 811 812In the ipsec-secgw/test directory 813 814to run one test for IPv4 or IPv6 815 816/bin/bash linux_test(4|6).sh <ipsec_mode> 817 818to run all tests for IPv4 or IPv6 819 820/bin/bash run_test.sh -4|-6 821 822For the list of available modes please refer to run_test.sh. 823