extras/vpp_config/README.rst

   1 VPP configuration utility
   2 =========================
   3
   4 The purpose of the VPP configuration utility is to allow the user to configure
   5 VPP in a simple and safe manner. The utility takes input from the user and
   6 then modifies the key configuration files. The user can then examine these files
   7 to be sure they are correct and then actually apply the configuration. The user
   8 can also install a released and stable version of VPP. This is currently
   9 released with release 17.10.
  10
  11 VPP config Usage
  12 ----------------
  13
  14 The installation and executing of the VPP configuration utility is simple. First
  15 install the python pip module. Using pip install, then pip install vpp-config.
  16 Then simply type ``vpp-config`` and answer the questions. If you are not sure what
  17 to answer choose the default. For yes or no questions the capital letter
  18 designates the default. For example, for a question that shows [Y/n] Y is the
  19 default. For numbers the default is within the brackets for example for a
  20 question that shows [1024]. 1024 is the default.
  21
  22 The flow of the utility is to inspect the system, if VPP is not install it,
  23 create dry run configurations, inspect the files created during the dry run,
  24 apply the configuration and then inspect the system again and then repeat.
  25
  26 Caveats
  27 -------
  28
  29 - Supports Ubuntu, centos7, RedHat is coming shortly.
  30
  31 For Developers:
  32
  33 Modifying the code is reasonable simple. The process would be edit and debug the
  34 code from the root directory. In order to do this, we need a script that will copy
  35 or data files to the proper place. This is where they end up with pip install. For
  36 Ubuntu, this is ``/usr/local/vpp/vpp-config``. I have provided a script that will copy
  37 the relevant files correctly. I have also provided a script that will clean the
  38 environment so you can start from scratch. These are the steps to run the utility
  39 in this environment. The scripts are meant to be run from the root directory.
  40
  41 .. code-block:: console
  42
  43     ./scripts/clean.sh
  44     ./scripts/cp-data.sh
  45     ./vpp-config
  46
  47 When the utility is installed with pip the wrapper ``scripts/vpp-config`` is written to
  48 ``/usr/local/bin``. However, the starting point when debugging this script locally is
  49 vpp-config. Run the utility by executing vpp-config.
  50
  51 The start point in the code is in vpp_config.py. However, most of the work is
  52 done in the files in ``./vpplib``
  53
  54 Uploading to PyPi
  55 -----------------
  56
  57 To upload this utility to PpPi simple do the following. Currently, I have my own account
  58 when we want everyone to contribute we will need to change that.
  59
  60
  61 .. code-block:: console
  62
  63     sudo bash
  64     cd vpp_config
  65     python setup.py sdist bdist_wheel
  66     twine upload dist/*
  67
  68 Example Run:
  69
  70 .. code-block:: console
  71
  72     # pip install vpp-config
  73     # vpp-config
  74
  75     Welcome to the VPP system configuration utility
  76
  77     These are the files we will modify:
  78
  79     /etc/vpp/startup.conf
  80     /etc/sysctl.d/80-vpp.conf
  81     /etc/default/grub
  82
  83     Before we change them, we'll create working copies in ``/usr/local/vpp/vpp-config/dryrun``
  84     Please inspect them carefully before applying the actual configuration (option 3)!
  85
  86     What would you like to do?
  87
  88     1) Show basic system information
  89     2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection)
  90         and user input in /usr/local/vpp/vpp-config/configs/auto-config.yaml
  91     3) Full configuration (WARNING: This will change the system configuration)
  92     4) Install/Uninstall VPP.
  93     5) Dry Run from /usr/local/vpp/vpp-config/auto-config.yaml (will not ask questions).
  94     6) Install QEMU patch (Needed when running openstack).
  95     9 or q) Quit
  96
  97     Command: 1
  98
  99     NODE: DUT1
 100
 101     CPU:
 102               Model name:    Intel(R) Xeon(R) CPU E5-2667 v3 @ 3.20GHz
 103                   CPU(s):    32
 104       Thread(s) per core:    2
 105       Core(s) per socket:    8
 106               Socket(s):    2
 107       NUMA node0 CPU(s):    0-7,16-23
 108       NUMA node1 CPU(s):    8-15,24-31
 109             CPU max MHz:    3600.0000
 110             CPU min MHz:    1200.0000
 111                     SMT:    Enabled
 112
 113     VPP Threads: (Name: Cpu Number)
 114
 115     Grub Command Line:
 116       Current: BOOT_IMAGE=/boot/vmlinuz-4.4.0-96-generic root=UUID=d760b82f-f37b-47e2-9815-db8d479a3557 ro
 117       Configured: GRUB_CMDLINE_LINUX_DEFAULT=""
 118
 119     Huge Pages:
 120       Total System Memory           : 65863484 kB
 121       Total Free Memory             : 41325924 kB
 122       Actual Huge Page Total        : 8192
 123       Configured Huge Page Total    : 1024
 124       Huge Pages Free               : 8192
 125       Huge Page Size                : 2048 kB
 126
 127     Devices:
 128
 129     Status:
 130       Not Installed
 131
 132     What would you like to do?
 133
 134     1) Show basic system information
 135     2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection)
 136         and user input in /usr/local/vpp/vpp-config/configs/auto-config.yaml
 137     3) Full configuration (WARNING: This will change the system configuration)
 138     4) Install/Uninstall VPP.
 139     5) Dry Run from /usr/local/vpp/vpp-config/auto-config.yaml (will not ask questions).
 140     6) Install QEMU patch (Needed when running openstack).
 141     9 or q) Quit
 142
 143     Command: 4
 144
 145     There are no VPP packages on node localhost.
 146     Do you want to install VPP [Y/n]?
 147     INFO:root: Local Command: ls /etc/apt/sources.list.d/99fd.io.list.orig
 148     INFO:root:  /etc/apt/sources.list.d/99fd.io.list.orig
 149
 150     What would you like to do?
 151
 152     1) Show basic system information
 153     2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection)
 154         and user input in /usr/local/vpp/vpp-config/configs/auto-config.yaml
 155     3) Full configuration (WARNING: This will change the system configuration)
 156     4) Install/Uninstall VPP.
 157     5) Dry Run from /usr/local/vpp/vpp-config/auto-config.yaml (will not ask questions).
 158     6) Install QEMU patch (Needed when running openstack).
 159     9 or q) Quit
 160
 161     Command: 1
 162
 163     ==============================
 164     NODE: DUT1
 165
 166     CPU:
 167               Model name:    Intel(R) Xeon(R) CPU E5-2667 v3 @ 3.20GHz
 168                   CPU(s):    32
 169       Thread(s) per core:    2
 170       Core(s) per socket:    8
 171               Socket(s):    2
 172       NUMA node0 CPU(s):    0-7,16-23
 173       NUMA node1 CPU(s):    8-15,24-31
 174             CPU max MHz:    3600.0000
 175             CPU min MHz:    1200.0000
 176                     SMT:    Enabled
 177
 178     VPP Threads: (Name: Cpu Number)
 179       vpp_main  : 0
 180       vpp_stats : 0
 181
 182     Grub Command Line:
 183       Current: BOOT_IMAGE=/boot/vmlinuz-4.4.0-96-generic root=UUID=d760b82f-f37b-47e2-9815-db8d479a3557 ro
 184       Configured: GRUB_CMDLINE_LINUX_DEFAULT=""
 185
 186     Huge Pages:
 187       Total System Memory           : 65863484 kB
 188       Total Free Memory             : 55877364 kB
 189       Actual Huge Page Total        : 1024
 190       Configured Huge Page Total    : 1024
 191       Huge Pages Free               : 1024
 192       Huge Page Size                : 2048 kB
 193
 194     Devices:
 195     Name                           Socket RXQs RXDescs TXQs TXDescs
 196
 197     Status:
 198       active (running)
 199
 200     ==============================
 201
 202     What would you like to do?
 203
 204     1) Show basic system information
 205     2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection)
 206         and user input in /usr/local/vpp/vpp-config/configs/auto-config.yaml
 207     3) Full configuration (WARNING: This will change the system configuration)
 208     4) Install/Uninstall VPP.
 209     5) Dry Run from /usr/local/vpp/vpp-config/auto-config.yaml (will not ask questions).
 210     6) Install QEMU patch (Needed when running openstack).
 211     9 or q) Quit
 212
 213     Command: 2
 214
 215     These device(s) are currently NOT being used by VPP or the OS.
 216
 217     PCI ID          Description
 218     ----------------------------------------------------------------
 219     0000:02:00.0    82599ES 10-Gigabit SFI/SFP+ Network Connection
 220     0000:02:00.1    82599ES 10-Gigabit SFI/SFP+ Network Connection
 221
 222     Would you like to give any of these devices back to the OS [y/N]? y
 223     Would you like to use device 0000:02:00.0 for the OS [y/N]? y
 224     Would you like to use device 0000:02:00.1 for the OS [y/N]? y
 225
 226     These devices have kernel interfaces, but appear to be safe to use with VPP.
 227
 228     PCI ID          Kernel Interface(s)       Description
 229     ------------------------------------------------------------------------------------------
 230     0000:90:00.0    enp144s0                  VIC Ethernet NIC
 231     0000:8f:00.0    enp143s0                  VIC Ethernet NIC
 232     0000:84:00.0    enp132s0f0,enp132s0f0d1   Ethernet Controller XL710 for 40GbE QSFP+
 233     0000:84:00.1    enp132s0f1,enp132s0f1d1   Ethernet Controller XL710 for 40GbE QSFP+
 234     0000:08:00.1    enp8s0f1                  I350 Gigabit Network Connection
 235     0000:02:00.0    enp2s0f0                  82599ES 10-Gigabit SFI/SFP+ Network Connection
 236     0000:02:00.1    enp2s0f1                  82599ES 10-Gigabit SFI/SFP+ Network Connection
 237     0000:86:00.0    enp134s0f0                82599ES 10-Gigabit SFI/SFP+ Network Connection
 238     0000:86:00.1    enp134s0f1                82599ES 10-Gigabit SFI/SFP+ Network Connection
 239
 240     Would you like to use any of these device(s) for VPP [y/N]? y
 241     Would you like to use device 0000:90:00.0 for VPP [y/N]?
 242     Would you like to use device 0000:8f:00.0 for VPP [y/N]?
 243     Would you like to use device 0000:84:00.0 for VPP [y/N]?
 244     Would you like to use device 0000:84:00.1 for VPP [y/N]?
 245     Would you like to use device 0000:08:00.1 for VPP [y/N]?
 246     Would you like to use device 0000:02:00.0 for VPP [y/N]? y
 247     Would you like to use device 0000:02:00.1 for VPP [y/N]? y
 248     Would you like to use device 0000:86:00.0 for VPP [y/N]? y
 249     Would you like to use device 0000:86:00.1 for VPP [y/N]? y
 250
 251     PCI ID          Description
 252     ----------------------------------------------------------------
 253     0000:86:00.0    82599ES 10-Gigabit SFI/SFP+ Network Connection
 254     0000:86:00.1    82599ES 10-Gigabit SFI/SFP+ Network Connection
 255     0000:02:00.0    82599ES 10-Gigabit SFI/SFP+ Network Connection
 256     0000:02:00.1    82599ES 10-Gigabit SFI/SFP+ Network Connection
 257
 258     Would you like to remove any of these device(s) [y/N]?
 259
 260     These device(s) will be used by VPP, please rerun this option if this is incorrect.
 261
 262     PCI ID          Description
 263     ----------------------------------------------------------------
 264     0000:86:00.0    82599ES 10-Gigabit SFI/SFP+ Network Connection
 265     0000:86:00.1    82599ES 10-Gigabit SFI/SFP+ Network Connection
 266     0000:02:00.0    82599ES 10-Gigabit SFI/SFP+ Network Connection
 267     0000:02:00.1    82599ES 10-Gigabit SFI/SFP+ Network Connection
 268
 269     Your system has 32 core(s) and 2 Numa Nodes.
 270     To begin, we suggest not reserving any cores for VPP or other processes.
 271     Then to improve performance try reserving cores as needed.
 272
 273     How many core(s) do you want to reserve for processes other than VPP? [0-16][0]? 4
 274     How many core(s) shall we reserve for VPP workers[0-4][0]? 2
 275     Should we reserve 1 core for the VPP Main thread? [Y/n]?
 276
 277     There currently 1024 2048 kB huge pages free.
 278     Do you want to reconfigure the number of huge pages [y/N]? y
 279
 280     There currently a total of 1024 huge pages.
 281     How many huge pages do you want [1024 - 22511][1024]? 8192
 282
 283     What would you like to do?
 284
 285     1) Show basic system information
 286     2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection)
 287         and user input in /usr/local/vpp/vpp-config/configs/auto-config.yaml
 288     3) Full configuration (WARNING: This will change the system configuration)
 289     4) Install/Uninstall VPP.
 290     5) Dry Run from /usr/local/vpp/vpp-config/auto-config.yaml (will not ask questions).
 291     6) Install QEMU patch (Needed when running openstack).
 292     9 or q) Quit
 293
 294     Command: 3
 295
 296     We are now going to configure your system(s).
 297
 298     Are you sure you want to do this [Y/n]?
 299     These are the changes we will apply to
 300     the huge page file (/etc/sysctl.d/80-vpp.conf).
 301
 302     1,2d0
 303     < # Number of 2MB hugepages desired
 304     < vm.nr_hugepages=1024
 305     4,7c2,3
 306     < # Must be greater than or equal to (2 * vm.nr_hugepages).
 307     < vm.max_map_count=3096
 308     <
 309     < # All groups allowed to access hugepages
 310     ---
 311     > vm.nr_hugepages=8192
 312     > vm.max_map_count=17408
 313     8a5
 314     > kernel.shmmax=17179869184
 315     10,15d6
 316     < # Shared Memory Max must be greator or equal to the total size of hugepages.
 317     < # For 2MB pages, TotalHugepageSize = vm.nr_hugepages * 2 * 1024 * 1024
 318     < # If the existing kernel.shmmax setting  (cat /sys/proc/kernel/shmmax)
 319     < # is greater than the calculated TotalHugepageSize then set this parameter
 320     < # to current shmmax value.
 321     < kernel.shmmax=2147483648
 322
 323     Are you sure you want to apply these changes [Y/n]?
 324     These are the changes we will apply to
 325     the VPP startup file (/etc/vpp/startup.conf).
 326
 327     3c3
 328     <   nodaemon
 329     ---
 330     >   interactive
 331     5a6
 332     >   cli-listen /run/vpp/cli.sock
 333     17c18,25
 334     <     ## In the VPP there is one main thread and optionally the user can create worker(s)
 335     ---
 336     >
 337     >   main-core 8
 338     >   corelist-workers 9-10,5-6
 339     >
 340     >   scheduler-policy fifo
 341     >   scheduler-priority 50
 342     >
 343     >         ## In the VPP there is one main thread and optionally the user can create worker(s)
 344     52,53c60,76
 345     < # dpdk {
 346     <     ## Change default settings for all intefaces
 347     ---
 348     > dpdk {
 349     >
 350     >   dev 0000:86:00.0 {
 351     >     num-rx-queues 2
 352     >   }
 353     >   dev 0000:86:00.1 {
 354     >     num-rx-queues 2
 355     >   }
 356     >   dev 0000:02:00.0 {
 357     >     num-rx-queues 2
 358     >   }
 359     >   dev 0000:02:00.1 {
 360     >     num-rx-queues 2
 361     >   }
 362     >   num-mbufs 71680
 363     >
 364     >         ## Change default settings for all intefaces
 365     82a106,115
 366     >     ## Specify bonded interface and its slaves via PCI addresses
 367     >     ##
 368     >         ## Bonded interface in XOR load balance mode (mode 2) with L3 and L4 headers
 369     >     # vdev eth_bond0,mode=2,slave=0000:02:00.0,slave=0000:03:00.0,xmit_policy=l34
 370     >     # vdev eth_bond1,mode=2,slave=0000:02:00.1,slave=0000:03:00.1,xmit_policy=l34
 371     >     ##
 372     >     ## Bonded interface in Active-Back up mode (mode 1)
 373     >     # vdev eth_bond0,mode=1,slave=0000:02:00.0,slave=0000:03:00.0
 374     >     # vdev eth_bond1,mode=1,slave=0000:02:00.1,slave=0000:03:00.1
 375     >
 376     99c132
 377     < # }
 378     ---
 379     > }
 380     108a142
 381     >
 382
 383     Are you sure you want to apply these changes [Y/n]?
 384
 385     The configured grub cmdline looks like this:
 386     GRUB_CMDLINE_LINUX_DEFAULT="intel_pstate=disable isolcpus=1-4,8,9-10,5-6 nohz_full=1-4,8,9-10,5-6 rcu_nocbs=1-4,8,9-10,5-6"
 387
 388     The current boot cmdline looks like this:
 389     BOOT_IMAGE=/boot/vmlinuz-4.4.0-96-generic root=UUID=d760b82f-f37b-47e2-9815-db8d479a3557 ro
 390
 391     Do you want to keep the current boot cmdline [Y/n]?
 392
 393     What would you like to do?
 394
 395     1) Show basic system information
 396     2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection)
 397         and user input in /usr/local/vpp/vpp-config/configs/auto-config.yaml
 398     3) Full configuration (WARNING: This will change the system configuration)
 399     4) Install/Uninstall VPP.
 400     5) Dry Run from /usr/local/vpp/vpp-config/auto-config.yaml (will not ask questions).
 401     6) Install QEMU patch (Needed when running openstack).
 402     9 or q) Quit
 403
 404     Command: 1
 405
 406     ==============================
 407     NODE: DUT1
 408
 409     CPU:
 410               Model name:    Intel(R) Xeon(R) CPU E5-2667 v3 @ 3.20GHz
 411                   CPU(s):    32
 412       Thread(s) per core:    2
 413       Core(s) per socket:    8
 414               Socket(s):    2
 415       NUMA node0 CPU(s):    0-7,16-23
 416       NUMA node1 CPU(s):    8-15,24-31
 417             CPU max MHz:    3600.0000
 418             CPU min MHz:    1200.0000
 419                     SMT:    Enabled
 420
 421     VPP Threads: (Name: Cpu Number)
 422
 423     Grub Command Line:
 424       Current: BOOT_IMAGE=/boot/vmlinuz-4.4.0-96-generic root=UUID=d760b82f-f37b-47e2-9815-db8d479a3557 ro
 425       Configured: GRUB_CMDLINE_LINUX_DEFAULT="intel_pstate=disable isolcpus=1-4,8,9-10,5-6 nohz_full=1-4,8,9-10,5-6 rcu_nocbs=1-4,8,9-10,5-6"
 426
 427     Huge Pages:
 428       Total System Memory           : 65863484 kB
 429       Total Free Memory             : 41163916 kB
 430       Actual Huge Page Total        : 8192
 431       Configured Huge Page Total    : 8192
 432       Huge Pages Free               : 3108
 433       Huge Page Size                : 2048 kB
 434
 435     Devices:
 436     Total Number of Buffers: 71680
 437
 438     Status:
 439       active (running)
 440       Sep 27 12:49:59 tf-ucs-3 vpp[13671]: EAL: No free hugepages reported in hugepages-1048576kB
 441
 442     ==============================
 443
 444     What would you like to do?
 445
 446     1) Show basic system information
 447     2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection)
 448         and user input in /usr/local/vpp/vpp-config/configs/auto-config.yaml
 449     3) Full configuration (WARNING: This will change the system configuration)
 450     4) Install/Uninstall VPP.
 451     5) Dry Run from /usr/local/vpp/vpp-config/auto-config.yaml (will not ask questions).
 452     6) Install QEMU patch (Needed when running openstack).
 453     9 or q) Quit
 454
 455     Command: 1
 456
 457     ==============================
 458     NODE: DUT1
 459
 460     CPU:
 461               Model name:    Intel(R) Xeon(R) CPU E5-2667 v3 @ 3.20GHz
 462                   CPU(s):    32
 463       Thread(s) per core:    2
 464       Core(s) per socket:    8
 465               Socket(s):    2
 466       NUMA node0 CPU(s):    0-7,16-23
 467       NUMA node1 CPU(s):    8-15,24-31
 468             CPU max MHz:    3600.0000
 469             CPU min MHz:    1200.0000
 470                     SMT:    Enabled
 471
 472     VPP Threads: (Name: Cpu Number)
 473       vpp_stats : 0
 474       vpp_wk_2  : 9
 475       vpp_wk_3  : 10
 476       vpp_wk_0  : 5
 477       vpp_wk_1  : 6
 478       vpp_main  : 8
 479
 480     Grub Command Line:
 481       Current: BOOT_IMAGE=/boot/vmlinuz-4.4.0-96-generic root=UUID=d760b82f-f37b-47e2-9815-db8d479a3557 ro
 482       Configured: GRUB_CMDLINE_LINUX_DEFAULT="intel_pstate=disable isolcpus=1-4,8,9-10,5-6 nohz_full=1-4,8,9-10,5-6 rcu_nocbs=1-4,8,9-10,5-6"
 483
 484     Huge Pages:
 485       Total System Memory           : 65863484 kB
 486       Total Free Memory             : 41170684 kB
 487       Actual Huge Page Total        : 8192
 488       Configured Huge Page Total    : 8192
 489       Huge Pages Free               : 7936
 490       Huge Page Size                : 2048 kB
 491
 492     Devices:
 493     Total Number of Buffers: 71680
 494     Name                           Socket RXQs RXDescs TXQs TXDescs
 495     TenGigabitEthernet2/0/0             0    2    1024    5    1024
 496     TenGigabitEthernet2/0/1             0    2    1024    5    1024
 497     TenGigabitEthernet86/0/0            1    2    1024    5    1024
 498     TenGigabitEthernet86/0/1            1    2    1024    5    1024
 499
 500     Status:
 501       active (running)
 502
 503     ==============================
 504
 505     What would you like to do?
 506
 507     1) Show basic system information
 508     2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection)
 509         and user input in /usr/local/vpp/vpp-config/configs/auto-config.yaml
 510     3) Full configuration (WARNING: This will change the system configuration)
 511     4) Install/Uninstall VPP.
 512     5) Dry Run from /usr/local/vpp/vpp-config/auto-config.yaml (will not ask questions).
 513     6) Install QEMU patch (Needed when running openstack).
 514     9 or q) Quit
 515
 516     Command: q
 517     #