diff options
Diffstat (limited to 'docs/gettingstarted/users/configutil')
| -rw-r--r-- | docs/gettingstarted/users/configutil/commandfour.rst | 114 | ||||
| -rw-r--r-- | docs/gettingstarted/users/configutil/commandone.rst | 70 | ||||
| -rw-r--r-- | docs/gettingstarted/users/configutil/commandthree.rst | 80 | ||||
| -rw-r--r-- | docs/gettingstarted/users/configutil/commandtwo.rst | 124 | ||||
| -rw-r--r-- | docs/gettingstarted/users/configutil/configapplied.rst | 85 | ||||
| -rw-r--r-- | docs/gettingstarted/users/configutil/index.rst | 30 | ||||
| -rw-r--r-- | docs/gettingstarted/users/configutil/installing.rst | 30 | ||||
| -rw-r--r-- | docs/gettingstarted/users/configutil/sysinfo.rst | 50 | ||||
| -rw-r--r-- | docs/gettingstarted/users/configutil/usingvppconfig.rst | 51 |
9 files changed, 634 insertions, 0 deletions
diff --git a/docs/gettingstarted/users/configutil/commandfour.rst b/docs/gettingstarted/users/configutil/commandfour.rst new file mode 100644 index 00000000000..27cac824e4a --- /dev/null +++ b/docs/gettingstarted/users/configutil/commandfour.rst @@ -0,0 +1,114 @@ +.. _config-command-four: + +************************** +List/Install/Uninstall VPP +************************** + +With option "4" the user can list, install or uninstall the FD.io VPP packages. If there +are packages already installed, the packages will be listed and then the user will be asked +if the packages should be uninstalled. If no packages are installed the user will be asked if +the FD.io packages should be installed. The packages installed will be the latest released +packages. + +Uninstalling the packages: + +.. code-block:: console + + What would you like to do? + + 1) Show basic system information + 2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection) + 3) Full configuration (WARNING: This will change the system configuration) + 4) List/Install/Uninstall VPP. + q) Quit + + Command: 4 + + These packages are installed on node localhost + Name Version + vpp 18.04-release + vpp-api-java 18.04-release + vpp-api-lua 18.04-release + vpp-api-python 18.04-release + vpp-dbg 18.04-release + vpp-dev 18.04-release + vpp-dpdk-dev 17.01.1-release + vpp-dpdk-dkms 17.01.1-release + vpp-lib 18.04-release + vpp-nsh-plugin 18.04 + vpp-nsh-plugin-dbg 18.04 + vpp-nsh-plugin-dev 18.04 + vpp-plugins 18.04-release + + Do you want to uninstall these packages [y/N]? y + INFO:root: Local Command: service vpp stop + INFO:root:Uninstall Ubuntu + INFO:root: Local Command: dpkg -l | grep vpp + .... + What would you like to do? + + 1) Show basic system information + 2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection) + 3) Full configuration (WARNING: This will change the system configuration) + 4) List/Install/Uninstall VPP. + q) Quit + + Command: + +Installing the packages: + +.. code-block:: console + + 1) Show basic system information + 2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection) + 3) Full configuration (WARNING: This will change the system configuration) + 4) List/Install/Uninstall VPP. + q) Quit + + Command: 4 + + There are no VPP packages on node localhost. + Do you want to install VPP [Y/n]? Y + INFO:root: Ubuntu + INFO:root:Install Ubuntu + INFO:root: Local Command: ls /etc/apt/sources.list.d/99fd.io.list.orig + INFO:root: /etc/apt/sources.list.d/99fd.io.list.orig + .... + + What would you like to do? + + 1) Show basic system information + 2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection) + 3) Full configuration (WARNING: This will change the system configuration) + 4) List/Install/Uninstall VPP. + q) Quit + + Command: 4 + + These packages are installed on node localhost + Name Version + vpp 18.04-release + vpp-api-java 18.04-release + vpp-api-lua 18.04-release + vpp-api-python 18.04-release + vpp-dbg 18.04-release + vpp-dev 18.04-release + vpp-dpdk-dev 17.01.1-release + vpp-dpdk-dkms 17.01.1-release + vpp-lib 18.04-release + vpp-nsh-plugin 18.04 + vpp-nsh-plugin-dbg 18.04 + vpp-nsh-plugin-dev 18.04 + vpp-plugins 18.04-release + + Do you want to uninstall these packages [y/N]? N + + What would you like to do? + + 1) Show basic system information + 2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection) + 3) Full configuration (WARNING: This will change the system configuration) + 4) List/Install/Uninstall VPP. + q) Quit + + Command: diff --git a/docs/gettingstarted/users/configutil/commandone.rst b/docs/gettingstarted/users/configutil/commandone.rst new file mode 100644 index 00000000000..9d63809b96b --- /dev/null +++ b/docs/gettingstarted/users/configutil/commandone.rst @@ -0,0 +1,70 @@ +.. _config-command-one: + +*********************** +Show System Information +*********************** + +With option "1" the user can inspect the system characteristics. + +This example shows a system that VPP has not yet been installed. + +.. code-block:: console + + What would you like to do? + + 1) Show basic system information + 2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection) + 3) Full configuration (WARNING: This will change the system configuration) + 4) List/Install/Uninstall VPP. + q) Quit + + Command: 1 + + ============================== + NODE: DUT1 + + CPU: + Model name: Intel(R) Xeon(R) CPU E5-2667 v3 @ 3.20GHz + CPU(s): 32 + Thread(s) per core: 2 + Core(s) per socket: 8 + Socket(s): 2 + NUMA node0 CPU(s): 0-7,16-23 + NUMA node1 CPU(s): 8-15,24-31 + CPU max MHz: 3600.0000 + CPU min MHz: 1200.0000 + SMT: Enabled + + VPP Threads: (Name: Cpu Number) + + Grub Command Line: + Current: BOOT_IMAGE=/vmlinuz-4.4.0-128-generic root=UUID=9930aeee-b1d3-4cf5-b0de-d95dbb7dec5e ro + Configured: GRUB_CMDLINE_LINUX_DEFAULT="isolcpus=8,9-10 nohz_full=8,9-10 rcu_nocbs=8,9-10" + + Huge Pages: + Total System Memory : 65863384 kB + Total Free Memory : 45911100 kB + Actual Huge Page Total : 1024 + Configured Huge Page Total : 8192 + Huge Pages Free : 896 + Huge Page Size : 2048 kB + + Devices: + Total Number of Buffers: 25600 + + Devices with link up (can not be used with VPP): + 0000:08:00.0 enp8s0f0 I350 Gigabit Network Connection + + Devices bound to kernel drivers: + 0000:90:00.0 enp144s0 VIC Ethernet NIC + 0000:8f:00.0 enp143s0 VIC Ethernet NIC + 0000:84:00.0 enp132s0f0,enp132s0f0d1 Ethernet Controller XL710 for 40GbE QSFP+ + 0000:84:00.1 enp132s0f1,enp132s0f1d1 Ethernet Controller XL710 for 40GbE QSFP+ + 0000:08:00.1 enp8s0f1 I350 Gigabit Network Connection + 0000:02:00.0 enp2s0f0 82599ES 10-Gigabit SFI/SFP+ Network Connection + 0000:02:00.1 enp2s0f1 82599ES 10-Gigabit SFI/SFP+ Network Connection + + No devices bound to DPDK drivers + + VPP Service Status: + Not Installed diff --git a/docs/gettingstarted/users/configutil/commandthree.rst b/docs/gettingstarted/users/configutil/commandthree.rst new file mode 100644 index 00000000000..c4c44292fd0 --- /dev/null +++ b/docs/gettingstarted/users/configutil/commandthree.rst @@ -0,0 +1,80 @@ +.. _config-command-three: + +*********************** +Apply the Configuration +*********************** + +After the configuration files have been examined and are correct. The configuration +can be applied. After the configuration is applied use option "1" to check the +system configuration. Notice the default is NOT to change the grub file. If the option +to change the grub command line is selected a reboot of the system will be required. + +.. code-block:: console + + What would you like to do? + + 1) Show basic system information + 2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection) + 3) Full configuration (WARNING: This will change the system configuration) + 4) List/Install/Uninstall VPP. + q) Quit + + Command: 3 + + We are now going to configure your system(s). + + Are you sure you want to do this [Y/n]? y + These are the changes we will apply to + the huge page file (/etc/sysctl.d/80-vpp.conf). + + 1,2d0 + < vm.nr_hugepages=1024 + 4,7c2,3 + < vm.max_map_count=3096 + --- + > vm.nr_hugepages=8192 + > vm.max_map_count=17408 + 8a5 + > kernel.shmmax=17179869184 + 10,15d6 + < kernel.shmmax=2147483648 + + Are you sure you want to apply these changes [Y/n]? + These are the changes we will apply to + the VPP startup file (/etc/vpp/startup.conf). + + --- + > + > main-core 8 + > corelist-workers 9-10 + > + > scheduler-policy fifo + > scheduler-priority 50 + > + 67,68c56,66 + < # dpdk { + --- + > dpdk { + > + > dev 0000:86:00.0 { + > num-rx-queues 2 + > } + > dev 0000:86:00.1 { + > num-rx-queues 2 + > } + > num-mbufs 25600 + > + 124c122 + < # } + --- + > } + + Are you sure you want to apply these changes [Y/n]? + + The configured grub cmdline looks like this: + GRUB_CMDLINE_LINUX_DEFAULT="isolcpus=8,9-10 nohz_full=8,9-10 rcu_nocbs=8,9-10" + + The current boot cmdline looks like this: + BOOT_IMAGE=/boot/vmlinuz-4.4.0-97-generic root=UUID=d760b82f-f37b-47e2-9815-db8d479a3557 ro + + Do you want to keep the current boot cmdline [Y/n]? diff --git a/docs/gettingstarted/users/configutil/commandtwo.rst b/docs/gettingstarted/users/configutil/commandtwo.rst new file mode 100644 index 00000000000..0d06c1410e5 --- /dev/null +++ b/docs/gettingstarted/users/configutil/commandtwo.rst @@ -0,0 +1,124 @@ +.. _config-command-two: + +******* +Dry Run +******* + +With the config utility dry run option the important configuration files are created +so that the user can examine them and then if they look reasonable apply them with +option 3. The files for **Ubuntu** can be found in the root directory /usr/local/vpp/vpp-config/dryrun +and for **Centos** in /usr/vpp/vpp-config/dryrun. + +The important configuration files are **/etc/vpp/startup.conf**, **/etc/sysctl.d/80-vpp.conf**, +and **/etc/default/grub** + +Startup.conf +============ + +FD.io VPP startup parameters are configured in the file **/etc/vpp/startup.conf**. The +utility creates this file under the vpp-config root directory in vpp/startup.conf. +the values in this file come from the questions asked about the devices, cores, rx queues, +and tcp parameters. + +80-vpp.conf +=========== + +The huge page configuration comes by setting values in the file **/etc/sysctl.d/80-vpp.conf**. +The utility creates the file under the root directory in sysctl.d/80-vpp.conf. When asked the +question about huge pages the correct values are put in the dryrin file. + +grub +==== + +CPUs can be isolated for use by VPP or other processes such as VMs using the grub configuration +file. This file is **/etc/default/grub**. This file must be modified with care. It is possible to +make your system unusable if this file is modified incorrectly. The dry run file is located under +the vpp-config root directory and then default. + +********************* +Executing the Dry Run +********************* + +The following is an example of how to execute a dry run. Defaults should be picked first and then +the values increased accordingly. + +.. code-block:: console + + 1) Show basic system information + 2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection) + 3) Full configuration (WARNING: This will change the system configuration) + 4) List/Install/Uninstall VPP. + q) Quit + + Command: 2 + + These devices have kernel interfaces, but appear to be safe to use with VPP. + + PCI ID Kernel Interface(s) Description + ------------------------------------------------------------------------------------------ + 0000:8f:00.0 enp143s0 VIC Ethernet NIC + 0000:84:00.0 enp132s0f0,enp132s0f0d1 Ethernet Controller XL710 for 40GbE QSFP+ + 0000:84:00.1 enp132s0f1,enp132s0f1d1 Ethernet Controller XL710 for 40GbE QSFP+ + 0000:08:00.1 enp8s0f1 I350 Gigabit Network Connection + 0000:02:00.0 enp2s0f0 82599ES 10-Gigabit SFI/SFP+ Network Connection + 0000:02:00.1 enp2s0f1 82599ES 10-Gigabit SFI/SFP+ Network Connection + 0000:86:00.0 enp134s0f0 82599ES 10-Gigabit SFI/SFP+ Network Connection + 0000:86:00.1 enp134s0f1 82599ES 10-Gigabit SFI/SFP+ Network Connection + + Would you like to use any of these device(s) for VPP [y/N]? y + Would you like to use device 0000:8f:00.0 for VPP [y/N]? + Would you like to use device 0000:84:00.0 for VPP [y/N]? + Would you like to use device 0000:84:00.1 for VPP [y/N]? + Would you like to use device 0000:08:00.1 for VPP [y/N]? + Would you like to use device 0000:02:00.0 for VPP [y/N]? + Would you like to use device 0000:02:00.1 for VPP [y/N]? + Would you like to use device 0000:86:00.0 for VPP [y/N]? y + Would you like to use device 0000:86:00.1 for VPP [y/N]? y + + These device(s) will be used by VPP. + + PCI ID Description + ---------------------------------------------------------------- + 0000:86:00.0 82599ES 10-Gigabit SFI/SFP+ Network Connection + 0000:86:00.1 82599ES 10-Gigabit SFI/SFP+ Network Connection + 0000:90:00.0 VIC Ethernet NIC + + Would you like to remove any of these device(s) [y/N]? y + Would you like to remove 0000:86:00.0 [y/N]? + Would you like to remove 0000:86:00.1 [y/N]? + Would you like to remove 0000:90:00.0 [y/N]? y + + These device(s) will be used by VPP, please rerun this option if this is incorrect. + + PCI ID Description + ---------------------------------------------------------------- + 0000:86:00.0 82599ES 10-Gigabit SFI/SFP+ Network Connection + 0000:86:00.1 82599ES 10-Gigabit SFI/SFP+ Network Connection + + Your system has 32 core(s) and 2 Numa Nodes. + To begin, we suggest not reserving any cores for VPP or other processes. + Then to improve performance start reserving cores and adding queues as needed. + + How many core(s) shall we reserve for VPP [0-4][0]? 2 + How many core(s) do you want to reserve for processes other than VPP? [0-15][0]? + Should we reserve 1 core for the VPP Main thread? [y/N]? y + How many RX queues per port shall we use for VPP [1-4][1]? 2 + + How many active-open / tcp client sessions are expected [0-10000000][0]? + How many passive-open / tcp server sessions are expected [0-10000000][0]? + + There currently 896 2048 kB huge pages free. + Do you want to reconfigure the number of huge pages [y/N]? y + + There currently a total of 1024 huge pages. + How many huge pages do you want [1024 - 15644][1024]? 8192 + + What would you like to do? + + 1) Show basic system information + 2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection) + 3) Full configuration (WARNING: This will change the system configuration) + 4) List/Install/Uninstall VPP. + q) Quit + + Command: diff --git a/docs/gettingstarted/users/configutil/configapplied.rst b/docs/gettingstarted/users/configutil/configapplied.rst new file mode 100644 index 00000000000..70d483b4b7c --- /dev/null +++ b/docs/gettingstarted/users/configutil/configapplied.rst @@ -0,0 +1,85 @@ +.. _config-applied: + +************************* +The Configuration Applied +************************* + +After the configuration is applied the system parameters should be examined. + +.. code-block:: console + + What would you like to do? + + 1) Show basic system information + 2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection) + 3) Full configuration (WARNING: This will change the system configuration) + 4) List/Install/Uninstall VPP. + q) Quit + + Command: 1 + + ============================== + NODE: DUT1 + + CPU: + Model name: Intel(R) Xeon(R) CPU E5-2667 v3 @ 3.20GHz + CPU(s): 32 + Thread(s) per core: 2 + Core(s) per socket: 8 + Socket(s): 2 + NUMA node0 CPU(s): 0-7,16-23 + NUMA node1 CPU(s): 8-15,24-31 + CPU max MHz: 3600.0000 + CPU min MHz: 1200.0000 + SMT: Enabled + + VPP Threads: (Name: Cpu Number) + vpp_main : 8 + vpp_wk_1 : 10 + vpp_wk_0 : 9 + vpp_stats : 0 + + Grub Command Line: + Current: BOOT_IMAGE=/vmlinuz-4.4.0-128-generic root=UUID=9930aeee-b1d3-4cf5-b0de-d95dbb7dec5e ro + Configured: GRUB_CMDLINE_LINUX_DEFAULT="isolcpus=1,8,9-10 nohz_full=1,8,9-10 rcu_nocbs=1,8,9-10" + + Huge Pages: + Total System Memory : 65863384 kB + Total Free Memory : 31169292 kB + Actual Huge Page Total : 8196 + Configured Huge Page Total : 8196 + Huge Pages Free : 7942 + Huge Page Size : 2048 kB + + Devices: + Total Number of Buffers: 25600 + + Devices with link up (can not be used with VPP): + 0000:08:00.0 enp8s0f0 I350 Gigabit Network Connection + + Devices bound to kernel drivers: + 0000:90:00.0 enp144s0 VIC Ethernet NIC + 0000:8f:00.0 enp143s0 VIC Ethernet NIC + 0000:84:00.0 enp132s0f0,enp132s0f0d1 Ethernet Controller XL710 for 40GbE QSFP+ + 0000:84:00.1 enp132s0f1,enp132s0f1d1 Ethernet Controller XL710 for 40GbE QSFP+ + 0000:08:00.1 enp8s0f1 I350 Gigabit Network Connection + 0000:02:00.0 enp2s0f0 82599ES 10-Gigabit SFI/SFP+ Network Connection + 0000:02:00.1 enp2s0f1 82599ES 10-Gigabit SFI/SFP+ Network Connection + + Devices bound to DPDK drivers: + 0000:86:00.0 82599ES 10-Gigabit SFI/SFP+ Network Connection + 0000:86:00.1 82599ES 10-Gigabit SFI/SFP+ Network Connection + + Devices in use by VPP: + Name Socket RXQs RXDescs TXQs TXDescs + TenGigabitEthernet86/0/0 1 2 1024 3 1024 + TenGigabitEthernet86/0/1 1 2 1024 3 1024 + + VPP Service Status: + active (running) + +.. toctree:: + + sysinfo + + diff --git a/docs/gettingstarted/users/configutil/index.rst b/docs/gettingstarted/users/configutil/index.rst new file mode 100644 index 00000000000..6cf3a3076f3 --- /dev/null +++ b/docs/gettingstarted/users/configutil/index.rst @@ -0,0 +1,30 @@ +.. _configutil: + +######################### +VPP Configuration Utility +######################### + +This guide provides instructions on how to install and use the vpp configuration +utility. + +The FD.io VPP Configuration Utility, or vpp-config, allows the user to configure +FD.io VPP in a simple and safe manner. The utility takes input from the user and +creates the configuration files in a dry run directory. The user should then examine +these files for correctness. If the configuration files look correct, the user +can then apply the configuration. Once the configuration is applied the user +should then check the system configuration with the utility and see if it was +applied correctly. + +This utility also includes a utility that can be used to install or uninstall FD.io VPP +packages. This should be used to insure the latest tested release is installed. + +.. toctree:: + + installing + usingvppconfig + commandfour + commandone + commandtwo + commandthree + configapplied + diff --git a/docs/gettingstarted/users/configutil/installing.rst b/docs/gettingstarted/users/configutil/installing.rst new file mode 100644 index 00000000000..57929aef648 --- /dev/null +++ b/docs/gettingstarted/users/configutil/installing.rst @@ -0,0 +1,30 @@ +.. _installing: + +.. toctree:: + +********** +Installing +********** + +The FD.io VPP configuration utility uses the `Python Package Index <https://pypi.org>`__ +or "pypi". + +To install FD.io vpp-config first install python pip. + +For Ubuntu execute: + +.. code-block:: console + + $ sudo apt-get install python-pip + +For Centos execute: + +.. code-block:: console + + $ sudo yum install install python-pip + +Then install the config utility itself. + +.. code-block:: console + + $ sudo -H pip install vpp-config diff --git a/docs/gettingstarted/users/configutil/sysinfo.rst b/docs/gettingstarted/users/configutil/sysinfo.rst new file mode 100644 index 00000000000..893f94999ce --- /dev/null +++ b/docs/gettingstarted/users/configutil/sysinfo.rst @@ -0,0 +1,50 @@ +.. _sysinfo: + +CPU +--- + +The CPU section of the system information is a summary of the CPU characteristics of the system. +It is important to understand the CPU topology and frequency in order to understand what the VPP +performance characteristics would be. + +Threads +------- + +It usually is not needed, but VPP can be configured to run on isolated CPUs. In the example shown +VPP is configured with 2 workers. The main thread is also configured to run on a seperate CPU. The +stats thread will always run on CPU 0. This utilty will put the worker threads on CPUs that are +associated with the ports that are configured. + +Grub Command Line +----------------- + +In general the Grub command line does not need to be changed. If the system is running many processes +it may be neccessary to isolate CPUs for VPP or other processes. + +Huge Pages +---------- + +As default when VPP is configured the number of huge pages that will be configured will be 1024. +This may not be enough. This section will show the total system memory and how many are configured. + + +Devices +------- + +In the devices section we have the "Total Number of Buffers". This utility allocates the correct +number of buffers. The number of buffers are calculated from the number of rx queues. + +VPP will not use links that are up. Those devices are shown with this utility. + +The devices bound to the kernel are not being used by VPP, but can be. + +The devices that are being used by VPP are shown with the interface name be used with VPP. The +socket being used by the VPP port is also shown. Notice in this example the worker thread are +on the correct CPU. The number of RX, TX Descriptors and TX queues are calculated from the number +of RX queues. + + +VPP Service Status +------------------ + +The VPP service status, will be installed, not installed, running or not. diff --git a/docs/gettingstarted/users/configutil/usingvppconfig.rst b/docs/gettingstarted/users/configutil/usingvppconfig.rst new file mode 100644 index 00000000000..4f1ce6c3c30 --- /dev/null +++ b/docs/gettingstarted/users/configutil/usingvppconfig.rst @@ -0,0 +1,51 @@ +.. _usingvppconfig.rst: + +******* +Running +******* + +The vpp-config utility provides the user with several different menus. This allows the +user to configure ports, some performance characteristics, the number of huge pages +and install/uninstall the released FD.io packages. + +It is recommended that the menu options are executed in this order. + +#. :ref:`4) List/Install/Uninstall VPP <config-command-four>` +#. :ref:`1) Show basic system information <config-command-one>` +#. :ref:`2) Dry Run <config-command-two>` +#. :ref:`3) Full Configuration <config-command-three>` + +Once vpp-config is installed as a root user execute the following + +.. code-block:: console + + $ sudo -H bash + # vpp-config + + Welcome to the VPP system configuration utility + + These are the files we will modify: + /etc/vpp/startup.conf + /etc/sysctl.d/80-vpp.conf + /etc/default/grub + + Before we change them, we'll create working copies in /usr/local/vpp/vpp-config/dryrun + Please inspect them carefully before applying the actual configuration (option 3)! + + What would you like to do? + + 1) Show basic system information + 2) Dry Run (Will save the configuration files in /usr/local/vpp/vpp-config/dryrun for inspection) + 4) List/Install/Uninstall VPP. + q) Quit + + Command: + +Default Values +============== + +If you do not choose to modify the default for any of the questions prompted by vpp-config, +you may press the ENTER key to select the default options: + +* Questions that ask [Y/n], the capital letter Y is the default answer. +* Numbers have their default within brackets, such as in [1024], the 1024 is the default. |