docs/usecases/networksim.md

   1 Network Simulator Plugin
   2 ========================
   3
   4 Vpp includes a fairly capable network simulator plugin, which can
   5 simulate real-world round-trip times and a configurable network packet
   6 loss rate. It's perfect for evaluating the performance of a TCP stack
   7 under specified delay/bandwidth/loss conditions.
   8
   9 The "nsim" plugin cross-connects two physical interfaces at layer 2,
  10 introducing the specified delay and network loss
  11 parameters. Reconfiguration on the fly is OK, with the proviso that
  12 packets held in the network simulator scheduling wheel will be lost.
  13
  14 Configuration
  15 -------------
  16
  17 Configuration by debug CLI is simple. First, specify the simulator
  18 configuration: unidirectional delay (half of the desired RTT), the
  19 link bandwidth, and the expected average packet size. These parameters
  20 allow the network simulator allocate the right amount of buffering to
  21 produce the requested delay/bandwidth product.
  22
  23 ```
  24     set nsim delay 25.0 ms bandwidth 10 gbit packet-size 128
  25 ```
  26
  27 To simulate network packet drops, add either "packets-per-drop <nnnnn>" or
  28 "drop-fraction [0.0 ... 1.0]" parameters:
  29
  30 ```
  31     set nsim delay 25.0 ms bandwidth 10 gbit packet-size 128 packets-per-drop 10000
  32 ```
  33 Remember to configure the layer-2 cross-connect:
  34
  35 ```
  36     nsim enable-disable <interface-1> <interface-2>
  37 ```
  38
  39 Packet Generator Configuration
  40 ------------------------------
  41
  42 Here's a unit-test configuration for the vpp packet generator:
  43
  44 ```
  45   loop cre
  46   set int ip address loop0 11.22.33.1/24
  47   set int state loop0 up
  48
  49   loop cre
  50   set int ip address loop1 11.22.34.1/24
  51   set int state loop1 up
  52
  53   set nsim delay 1.0 ms bandwidth 10 gbit packet-size 128 packets-per-drop 1000
  54   nsim enable-disable loop0 loop1
  55
  56   packet-generator new {
  57       name s0
  58       limit 10000
  59       size 128-128
  60       interface loop0
  61       node ethernet-input
  62       data { IP4: 1.2.3 -> 4.5.6
  63              UDP: 11.22.33.44 -> 11.22.34.44
  64              UDP: 1234 -> 2345
  65              incrementing 114
  66       }
  67   }
  68 ```
  69
  70 For extra realism, the network simulator drops any specific packet
  71 with the specified probability. In this example, we see that slight
  72 variation from run to run occurs as it should.
  73
  74 ```
  75     DBGvpp# pa en
  76     DBGvpp# sh err
  77        Count                    Node                  Reason
  78           9991                  nsim                  Packets buffered
  79              9                  nsim                  Network loss simulation drop packets
  80           9991             ethernet-input             l3 mac mismatch
  81
  82     DBGvpp# clear err
  83     DBGvpp# pa en
  84     DBGvpp# sh err
  85     sh err
  86        Count                    Node                  Reason
  87           9993                  nsim                  Packets buffered
  88              7                  nsim                  Network loss simulation drop packets
  89           9993             ethernet-input             l3 mac mismatch
  90 ```