doc/guides/sample_app_ug/ipsec_secgw.rst

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