diff options
Diffstat (limited to 'docs/gettingstarted/users/configuring')
| -rw-r--r-- | docs/gettingstarted/users/configuring/hugepages.rst | 63 | ||||
| -rw-r--r-- | docs/gettingstarted/users/configuring/index.rst | 13 | ||||
| -rw-r--r-- | docs/gettingstarted/users/configuring/startup.rst | 1683 |
3 files changed, 0 insertions, 1759 deletions
diff --git a/docs/gettingstarted/users/configuring/hugepages.rst b/docs/gettingstarted/users/configuring/hugepages.rst deleted file mode 100644 index 7a1e0bd8057..00000000000 --- a/docs/gettingstarted/users/configuring/hugepages.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. _hugepages: - -Huge Pages ----------- - -VPP requires *hugepages* to run during VPP operation, to manage large pages of memory. -During VPP installation, VPP will overwrite the existing hugepage settings. -By default, VPP sets the number of hugepages on a system to 1024 2M hugepages. -This is the number of hugepages on the system, not just used by VPP. - -When VPP is installed, the following configuration file is copied to the system. The -hugepage settings are applied in the VPP installation and on system reboots. To set -the hugepage settings, perform the following commands: - -.. code-block:: console - - $ cat /etc/sysctl.d/80-vpp.conf - # Number of 2MB hugepages desired - vm.nr_hugepages=1024 - - # Must be greater than or equal to (2 * vm.nr_hugepages). - vm.max_map_count=3096 - - # All groups allowed to access hugepages - vm.hugetlb_shm_group=0 - - # Shared Memory Max must be greater or equal to the total size of hugepages. - # For 2MB pages, TotalHugepageSize = vm.nr_hugepages * 2 * 1024 * 1024 - # If the existing kernel.shmmax setting (cat /sys/proc/kernel/shmmax) - # is greater than the calculated TotalHugepageSize then set this parameter - # to current shmmax value. - kernel.shmmax=2147483648 - -Depending on how the system is being used, this configuration file can be updated to adjust -the number of hugepages reserved on a system. Below are some examples of -possible settings. - -For a small VM with minimal workload: - -.. code-block:: console - - vm.nr_hugepages=512 - vm.max_map_count=2048 - kernel.shmmax=1073741824 - -For a large system running multiple VMs, each needing its own set of hugepages: - -.. code-block:: console - - vm.nr_hugepages=32768 - vm.max_map_count=66560 - kernel.shmmax=68719476736 - - -.. note:: - - If VPP is being run in a Virtual Machine (VM), the VM must have hugepage - backing. When VPP is installed, it will attempt to overwrite existing the - hugepage setting. If the VM does not have hugepage backing, the install will fail, - but the failure may go unnoticed. When the VM is rebooted, on system startup, - *'vm.nr_hugepages'* will be reapplied, and will fail, and the VM will abort kernel - boot, locking up the VM. To avoid this scenario, ensure the VM has enough - hugepage backing. diff --git a/docs/gettingstarted/users/configuring/index.rst b/docs/gettingstarted/users/configuring/index.rst deleted file mode 100644 index 0de77adea6c..00000000000 --- a/docs/gettingstarted/users/configuring/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _configuring: - -Configuring VPP -================== - -There is some basic configuration that needs to be performed before running -FD.io VPP. This section describes the configuration process: - -.. toctree:: - :maxdepth: 2 - - hugepages - startup diff --git a/docs/gettingstarted/users/configuring/startup.rst b/docs/gettingstarted/users/configuring/startup.rst deleted file mode 100644 index e594b6a08a4..00000000000 --- a/docs/gettingstarted/users/configuring/startup.rst +++ /dev/null @@ -1,1683 +0,0 @@ -.. _startup: - -========================================== -VPP Configuration - CLI and 'startup.conf' -========================================== - -After a successful installation, VPP installs a startup config file named -*startup.conf* in the */etc/vpp/* directory. This file can be tailored to -make VPP run as desired, but contains default values for typical installations. - -Below are more details about this file and some of the the parameters and values -it contains. - -Command-line Arguments ----------------------- - -Before we describe details of the startup configuration file (startup.conf) it -should be mentioned that VPP can be started without a startup configuration -file. - -Parameters are grouped by a section name. When providing more than one -parameter to a section, all parameters for that section must be wrapped in -curly braces. For example, to start VPP with configuration data via the -command line with the section name *'unix'*: - -.. code-block:: console - - $ sudo /usr/bin/vpp unix { interactive cli-listen 127.0.0.1:5002 } - -The command line can be presented as a single string or as several; anything -given on the command line is concatenated with spaces into a single string -before parsing. VPP applications must be able to locate their own executable -images. The simplest way to ensure this will work is to invoke a VPP -application by giving its absolute path. For example: -*'/usr/bin/vpp <options>'* At startup, VPP applications parse through their -own ELF-sections [primarily] to make lists of init, configuration, and exit -handlers. - -When developing with VPP, in gdb it's often sufficient to start an application -like this: - -.. code-block:: console - - (gdb) run unix interactive - - -Startup Configuration File (startup.conf) ------------------------------------------ - -The more typical way to specify the startup configuration to VPP is with the -startup configuration file (startup.conf). - -The path of the file is provided to the VPP application on the command line. -This is typically at /etc/vpp/startup.conf. If VPP is installed as a package -a default startup.conf file is provided at this location. - -The format of the configuration file is a simple text file with the same content -as the command line. - -**A very simple startup.conf file:** - -.. code-block:: console - - $ cat /etc/vpp/startup.conf - unix { - nodaemon - log /var/log/vpp/vpp.log - full-coredump - cli-listen localhost:5002 - } - - api-trace { - on - } - - dpdk { - dev 0000:03:00.0 - } - -VPP is instructed to load this file with the -c option. For example: - -.. code-block:: console - - $ sudo /usr/bin/vpp -c /etc/vpp/startup.conf - -Configuration Parameters ------------------------- - -Below is the list of some section names and their associated parameters. -This is not an exhaustive list, but should give you an idea of how VPP can be configured. - -For all of the configuration parameters search the source code for instances of -**VLIB_CONFIG_FUNCTION** and **VLIB_EARLY_CONFIG_FUNCTION**. - -For example, the invocation *'VLIB_CONFIG_FUNCTION (foo_config, "foo")'* will -cause the function *'foo_config'* to receive all parameters given in a -parameter block named "foo": "foo { arg1 arg2 arg3 ... }". - -The unix section ----------------- - -Configures VPP startup and behavior type attributes, as well and any OS based -attributes. - -.. code-block:: console - - unix { - nodaemon - log /var/log/vpp/vpp.log - full-coredump - cli-listen /run/vpp/cli.sock - gid vpp - } - -nodaemon -^^^^^^^^ - -Do not fork / background the vpp process. Typical when invoking VPP -applications from a process monitor. Set by default in the default -*'startup.conf'* file. - -.. code-block:: console - - nodaemon - -nosyslog -^^^^^^^^ - -Disable syslog and log errors to stderr instead. Typical when invoking -VPP applications from a process monitor like runit or daemontools that -pipe service's output to a dedicated log service, which will typically -attach a timestamp and rotate the logs as necessary. - -.. code-block:: console - - nosyslog - -interactive -^^^^^^^^^^^ - -Attach CLI to stdin/out and provide a debugging command line interface. - -.. code-block:: console - - interactive - -log <filename> -^^^^^^^^^^^^^^ - -Logs the startup configuration and all subsequent CLI commands in filename. -Very useful in situations where folks don't remember or can't be bothered -to include CLI commands in bug reports. The default *'startup.conf'* file -is to write to *'/var/log/vpp/vpp.log'*. - -In VPP 18.04, the default log file location was moved from '/tmp/vpp.log' -to '/var/log/vpp/vpp.log' . The VPP code is indifferent to the file location. -However, if SELinux is enabled, then the new location is required for the file -to be properly labeled. Check your local *'startup.conf'* file for the log file -location on your system. - -.. code-block:: console - - log /var/log/vpp/vpp-debug.log - -exec | startup-config <filename> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Read startup operational configuration from filename. The contents of the file -will be performed as though entered at the CLI. The two keywords are aliases -for the same function; if both are specified, only the last will have an effect. - -A file of CLI commands might look like: - -.. code-block:: console - - $ cat /usr/share/vpp/scripts/interface-up.txt - set interface state TenGigabitEthernet1/0/0 up - set interface state TenGigabitEthernet1/0/1 up - -Parameter Example: - -.. code-block:: console - - startup-config /usr/share/vpp/scripts/interface-up.txt - -gid <number | name> -^^^^^^^^^^^^^^^^^^^ - -Sets the effective group ID to the input group ID or group name of the calling -process. - -.. code-block:: console - - gid vpp - -full-coredump -^^^^^^^^^^^^^ - -Ask the Linux kernel to dump all memory-mapped address regions, instead of -just text+data+bss. - -.. code-block:: console - - full-coredump - -coredump-size unlimited | <n>G | <n>M | <n>K | <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Set the maximum size of the coredump file. The input value can be set in - GB, MB, KB or bytes, or set to *'unlimited'*. - -.. code-block:: console - - coredump-size unlimited - -cli-listen <ipaddress:port> | <socket-path> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Bind the CLI to listen at address localhost on TCP port 5002. This will - accept an ipaddress:port pair or a filesystem path; in the latter case a - local Unix socket is opened instead. The default *'startup.conf'* file - is to open the socket *'/run/vpp/cli.sock'*. - -.. code-block:: console - - cli-listen localhost:5002 - cli-listen /run/vpp/cli.sock - -cli-line-mode -^^^^^^^^^^^^^ - - Disable character-by-character I/O on stdin. Useful when combined with, - for example, emacs M-x gud-gdb. - -.. code-block:: console - - cli-line-mode - -cli-prompt <string> -^^^^^^^^^^^^^^^^^^^ - - Configure the CLI prompt to be string. - -.. code-block:: console - - cli-prompt vpp-2 - -cli-history-limit <n> -^^^^^^^^^^^^^^^^^^^^^ - - Limit command history to <n> lines. A value of 0 disables command history. - Default value: 50 - -.. code-block:: console - - cli-history-limit 100 - -cli-no-banner -^^^^^^^^^^^^^ - - Disable the login banner on stdin and Telnet connections. - -.. code-block:: console - - cli-no-banner - -cli-no-pager -^^^^^^^^^^^^ - - Disable the output pager. - -.. code-block:: console - - cli-no-pager - -cli-pager-buffer-limit <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Limit pager buffer to <n> lines of output. A value of 0 disables the - pager. Default value: 100000 - -.. code-block:: console - - cli-pager-buffer-limit 5000 - -runtime-dir <dir> -^^^^^^^^^^^^^^^^^ - - Set the runtime directory, which is the default location for certain - files, like socket files. Default is based on User ID used to start VPP. - Typically it is *'root'*, which defaults to *'/run/vpp/'*. Otherwise, - defaults to *'/run/user/<uid>/vpp/'*. - -.. code-block:: console - - runtime-dir /tmp/vpp - -poll-sleep-usec <n> -^^^^^^^^^^^^^^^^^^^ - - Add a fixed-sleep between main loop poll. Default is 0, which is not to - sleep. - -.. code-block:: console - - poll-sleep-usec 100 - -pidfile <filename> -^^^^^^^^^^^^^^^^^^ - - Writes the pid of the main thread in the given filename. - -.. code-block:: console - - pidfile /run/vpp/vpp1.pid - - -The api-trace Section ---------------------- - -The ability to trace, dump, and replay control-plane API traces makes all the -difference in the world when trying to understand what the control-plane has -tried to ask the forwarding-plane to do. - -Typically, one simply enables the API message trace scheme: - -.. code-block:: console - - api-trace { - api-trace on - } - -on | enable -^^^^^^^^^^^ - - Enable API trace capture from the beginning of time, and arrange for a - post-mortem dump of the API trace if the application terminates abnormally. - By default, the (circular) trace buffer will be configured to capture - 256K traces. The default *'startup.conf'* file has trace enabled by default, - and unless there is a very strong reason, it should remain enabled. - -.. code-block:: console - - on - -nitems <n> -^^^^^^^^^^ - - Configure the circular trace buffer to contain the last <n> entries. By - default, the trace buffer captures the last 256K API messages received. - -.. code-block:: console - - nitems 524288 - -save-api-table <filename> -^^^^^^^^^^^^^^^^^^^^^^^^^ - - Dumps the API message table to /tmp/<filename>. - -.. code-block:: console - - save-api-table apiTrace-07-04.txt - - -The api-segment Section ------------------------ - -These values control various aspects of the binary API interface to VPP. - -The default looks like the following: - -.. code-block:: console - - api-segment { - gid vpp - } - - -prefix <path> -^^^^^^^^^^^^^ - - Sets the prefix prepended to the name used for shared memory (SHM) - segments. The default is empty, meaning shared memory segments are created - directly in the SHM directory *'/dev/shm'*. It is worth noting that on - many systems *'/dev/shm'* is a symbolic link to somewhere else in the file - system; Ubuntu links it to *'/run/shm'*. - -.. code-block:: console - - prefix /run/shm - -uid <number | name> -^^^^^^^^^^^^^^^^^^^ - - Sets the user ID or name that should be used to set the ownership of the - shared memory segments. Defaults to the same user that VPP is started - with, probably root. - -.. code-block:: console - - uid root - -gid <number | name> -^^^^^^^^^^^^^^^^^^^ - - Sets the group ID or name that should be used to set the ownership of the - shared memory segments. Defaults to the same group that VPP is started - with, probably root. - -.. code-block:: console - - gid vpp - -**The following parameters should only be set by those that are familiar with the -interworkings of VPP.** - -baseva <x> -^^^^^^^^^^ - - Set the base address for SVM global region. If not set, on AArch64, the - code will try to determine the base address. All other default to - 0x30000000. - -.. code-block:: console - - baseva 0x20000000 - -global-size <n>G | <n>M | <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Set the global memory size, memory shared across all router instances, - packet buffers, etc. If not set, defaults to 64M. The input value can be - set in GB, MB or bytes. - -.. code-block:: console - - global-size 2G - -global-pvt-heap-size <n>M | size <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Set the size of the global VM private mheap. If not set, defaults to 128k. - The input value can be set in MB or bytes. - -.. code-block:: console - - global-pvt-heap-size size 262144 - -api-pvt-heap-size <n>M | size <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Set the size of the api private mheap. If not set, defaults to 128k. - The input value can be set in MB or bytes. - -.. code-block:: console - - api-pvt-heap-size 1M - -api-size <n>M | <n>G | <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Set the size of the API region. If not set, defaults to 16M. The input - value can be set in GB, MB or bytes. - -.. code-block:: console - - api-size 64M - -The socksvr Section -------------------- - -Enables a Unix domain socket which processes binary API messages. See -.../vlibmemory/socket_api.c. If this parameter is not set, vpp -won't process binary API messages over sockets. - -.. code-block:: console - - socksvr { - # Explicitly name a socket file - socket-name /run/vpp/api.sock - or - # Use defaults as described below - default - } - -The "default" keyword instructs vpp to use /run/vpp/api.sock when -running as root, otherwise to use /run/user/<uid>/api.sock. - -The cpu Section ---------------- - -In the VPP there is one main thread and optionally the user can create worker(s) -The main thread and worker thread(s) can be pinned to CPU core(s) manually or automatically - -.. code-block:: console - - cpu { - main-core 1 - corelist-workers 2-3,18-19 - } - - -Manual pinning of thread(s) to CPU core(s) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -main-core -^^^^^^^^^ - -Set logical CPU core where main thread runs, if main core is not set VPP will use -core 1 if available - -.. code-block:: console - - main-core 1 - -corelist-workers -^^^^^^^^^^^^^^^^ - -Set logical CPU core(s) where worker threads are running - -.. code-block:: console - - corelist-workers 2-3,18-19 - -Automatic pinning of thread(s) to CPU core(s) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -skip-cores number -^^^^^^^^^^^^^^^^^ - -Sets number of CPU core(s) to be skipped (1 ... N-1), Skipped CPU core(s) are -not used for pinning main thread and working thread(s). - -The main thread is automatically pinned to the first available CPU core and worker(s) -are pinned to next free CPU core(s) after core assigned to main thread - -.. code-block:: console - - skip-cores 4 - -workers number -^^^^^^^^^^^^^^ - -Specify a number of workers to be created Workers are pinned to N consecutive -CPU cores while skipping "skip-cores" CPU core(s) and main thread's CPU core - -.. code-block:: console - - workers 2 - -scheduler-policy other | batch | idle | fifo | rr -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Set scheduling policy and priority of main and worker threads - -Scheduling policy options are: other (SCHED_OTHER), batch (SCHED_BATCH) -idle (SCHED_IDLE), fifo (SCHED_FIFO), rr (SCHED_RR) - -.. code-block:: console - - scheduler-policy fifo - -scheduler-priority number -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Scheduling priority is used only for "real-time policies (fifo and rr), -and has to be in the range of priorities supported for a particular policy - -.. code-block:: console - - scheduler-priority 50 - -The buffers Section -------------------- - -.. code-block:: console - - buffers { - buffers-per-numa 128000 - default data-size 2048 - page-size default-hugepage - } - -buffers-per-numa number -^^^^^^^^^^^^^^^^^^^^^^^ - -Increase number of buffers allocated, needed only in scenarios with -large number of interfaces and worker threads. Value is per numa node. -Default is 16384 (8192 if running unpriviledged) - -.. code-block:: console - - buffers-per-numa 128000 - -default data-size number -^^^^^^^^^^^^^^^^^^^^^^^^ - -Size of buffer data area, default is 2048 - -.. code-block:: console - - default data-size 2048 - -page-size number -^^^^^^^^^^^^^^^^ - -Set the page size for buffer allocation - -.. code-block:: console - - page-size 4K - page-size 2M - page-size 1G - page-size default - page-size default-hugepage - - -The dpdk Section ----------------- - -.. code-block:: console - - dpdk { - dev default { - num-rx-desc 512 - num-tx-desc 512 - } - - dev 0000:02:00.1 { - num-rx-queues 2 - name eth0 - } - } - -dev <pci-dev> | default { .. } -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -White-list [as in, attempt to drive] a specific PCI device. PCI-dev is a -string of the form "DDDD:BB:SS.F" where: - -* DDDD = Domain -* BB = Bus Number -* SS = Slot number -* F = Function - -If the keyword **default** is used the values will apply to all the devices. - -This is the same format used in the linux sysfs tree (i.e./sys/bus/pci/devices) -for PCI device directory names. - -.. code-block:: console - - dpdk { - dev default { - num-rx-desc 512 - num-tx-desc 512 - } - -dev <pci-dev> { .. } -^^^^^^^^^^^^^^^^^^^^ - -Whitelist specific interface by specifying PCI address. When whitelisting specific -interfaces by specifying PCI address, additional custom parameters can also be -specified. Valid options include: - -.. code-block:: console - - dev 0000:02:00.0 - dev 0000:03:00.0 - -blacklist <pci-dev> -^^^^^^^^^^^^^^^^^^^ - -Blacklist specific device type by specifying PCI vendor:device Whitelist entries -take precedence - -.. code-block:: console - - blacklist 8086:10fb - -name interface-name -^^^^^^^^^^^^^^^^^^^ - -Set interface name - -.. code-block:: console - - dev 0000:02:00.1 { - name eth0 - } - -num-rx-queues <n> -^^^^^^^^^^^^^^^^^ - -Number of receive queues. Also enables RSS. Default value is 1. - -.. code-block:: console - - dev 0000:02:00.1 { - num-rx-queues <n> - } - -num-tx-queues <n> -^^^^^^^^^^^^^^^^^ - -Number of transmit queues. Default is equal to number of worker threads -or 1 if no workers treads. - -.. code-block:: console - - dev 000:02:00.1 { - num-tx-queues <n> - } - -num-rx-desc <n> -^^^^^^^^^^^^^^^ - -Number of descriptors in receive ring. Increasing or reducing number -can impact performance. Default is 1024. - -.. code-block:: console - - dev 000:02:00.1 { - num-rx-desc <n> - } - -vlan-strip-offload on | off -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -VLAN strip offload mode for interface. VLAN stripping is off by default -for all NICs except VICs, using ENIC driver, which has VLAN stripping on -by default. - -.. code-block:: console - - dev 000:02:00.1 { - vlan-strip-offload on|off - } - -uio-driver driver-name -^^^^^^^^^^^^^^^^^^^^^^ - -Change UIO driver used by VPP, Options are: igb_uio, vfio-pci, uio_pci_generic -or auto (default) - - -.. code-block:: console - - uio-driver vfio-pci - -no-multi-seg -^^^^^^^^^^^^ - -Disable multi-segment buffers, improves performance but disables Jumbo MTU support - -.. code-block:: console - - no-multi-seg - -socket-mem <n> -^^^^^^^^^^^^^^ - -Change hugepages allocation per-socket, needed only if there is need for -larger number of mbufs. Default is 256M on each detected CPU socket - -.. code-block:: console - - socket-mem 2048,2048 - -no-tx-checksum-offload -^^^^^^^^^^^^^^^^^^^^^^ - -Disables UDP / TCP TX checksum offload. Typically needed for use faster -vector PMDs (together with no-multi-seg) - -.. code-block:: console - - no-tx-checksum-offload - -enable-tcp-udp-checksum -^^^^^^^^^^^^^^^^^^^^^^^ - -Enable UDP / TCP TX checksum offload This is the reversed option of -'no-tx-checksum-offload' - -.. code-block:: console - - enable-tcp-udp-checksum - -The plugins Section -------------------- - -Configure VPP plugins. - -.. code-block:: console - - plugins { - path /ws/vpp/build-root/install-vpp-native/vpp/lib/vpp_plugins - plugin dpdk_plugin.so enable - } - -path pathname -^^^^^^^^^^^^^ - -Adjust the plugin path depending on where the VPP plugins are. - -.. code-block:: console - - path /ws/vpp/build-root/install-vpp-native/vpp/lib/vpp_plugins - -plugin plugin-name | default enable | disable -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Disable all plugins by default and then selectively enable specific plugins - -.. code-block:: console - - plugin default disable - plugin dpdk_plugin.so enable - plugin acl_plugin.so enable - -Enable all plugins by default and then selectively disable specific plugins - -.. code-block:: console - - plugin dpdk_plugin.so disable - plugin acl_plugin.so disable - -Th statseg Section -^^^^^^^^^^^^^^^^^^ - -.. code-block:: console - - statseg { - per-node-counters on - } - -socket-name <filename> -^^^^^^^^^^^^^^^^^^^^^^ - -Name of the stats segment socket defaults to /run/vpp/stats.sock. - -.. code-block:: console - - socket-name /run/vpp/stats.sock - -size <nnn>[KMG] -^^^^^^^^^^^^^^^ - -The size of the stats segment, defaults to 32mb - -.. code-block:: console - - size 1024M - -per-node-counters on | off -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Defaults to none - -.. code-block:: console - - per-node-counters on - -update-interval <f64-seconds> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the segment scrape / update interval - -.. code-block:: console - - update-interval 300 - - -Some Advanced Parameters: -------------------------- - - -acl-plugin Section ------------------- - -These parameters change the configuration of the ACL (access control list) plugin, -such as how the ACL bi-hash tables are initialized. - -They should only be set by those that are familiar with the interworkings of VPP -and the ACL Plugin. - -The first three parameters, *connection hash buckets*, *connection hash memory*, -and *connection count max*, set the **connection table per-interface parameters** -for modifying how the two bounded-index extensible hash tables for -IPv6 (40\*8 bit key and 8\*8 bit value pairs) and IPv4 -(16\*8 bit key and 8\*8 bit value pairs) **ACL plugin FA interface sessions** -are initialized. - -connection hash buckets <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the number of hash buckets (rounded up to a power of 2) in each -of the two bi-hash tables. Defaults to 64\*1024 (65536) hash buckets. - -.. code-block:: console - - connection hash buckets 65536 - -connection hash memory <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the allocated memory size (in bytes) for each of the two bi-hash tables. -Defaults to 1073741824 bytes. - -.. code-block:: console - - connection hash memory 1073741824 - -connection count max <n> -^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the maximum number of pool elements when allocating each per-worker -pool of sessions for both bi-hash tables. Defaults to 500000 elements in each pool. - -.. code-block:: console - - connection count max 500000 - -main heap size <n>G | <n>M | <n>K | <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the size of the main memory heap that holds all the ACL module related -allocations (other than hash.) Default size is 0, but during -ACL heap initialization is equal to -*per_worker_size_with_slack * tm->n_vlib_mains + bihash_size + main_slack*. -Note that these variables are partially based on the -**connection table per-interface parameters** mentioned above. - -.. code-block:: console - - main heap size 3G - -The next three parameters, *hash lookup heap size*, *hash lookup hash buckets*, -and *hash lookup hash memory*, modify the initialization of the bi-hash lookup -table used by the ACL plugin. This table is initialized when attempting to apply -an ACL to the existing vector of ACLs looked up during packet processing -(but it is found that the table does not exist / has not been initialized yet.) - -hash lookup heap size <n>G | <n>M | <n> K | <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the size of the memory heap that holds all the miscellaneous allocations -related to hash-based lookups. Default size is 67108864 bytes. - -.. code-block:: console - - hash lookup heap size 70M - -hash lookup hash buckets <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the number of hash buckets (rounded up to a power of 2) in the bi-hash -lookup table. Defaults to 65536 hash buckets. - -.. code-block:: console - - hash lookup hash buckets 65536 - -hash lookup hash memory <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the allocated memory size (in bytes) for the bi-hash lookup table. -Defaults to 67108864 bytes. - -.. code-block:: console - - hash lookup hash memory 67108864 - -use tuple merge <n> -^^^^^^^^^^^^^^^^^^^ - -Sets a boolean value indicating whether or not to use TupleMerge -for hash ACL's. Defaults to 1 (true), meaning the default implementation -of hashing ACL's does use TupleMerge. - -.. code-block:: console - - use tuple merge 1 - -tuple merge split threshold <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the maximum amount of rules (ACE's) that can collide in a bi-hash -lookup table before the table is split into two new tables. Splitting ensures -less rule collisions by hashing colliding rules based on their common tuple -(usually their maximum common tuple.) Splitting occurs when the -*length of the colliding rules vector* is greater than this threshold amount. -Defaults to a maximum of 39 rule collisions per table. - -.. code-block:: console - - tuple merge split threshold 30 - -reclassify sessions <n> -^^^^^^^^^^^^^^^^^^^^^^^ - -Sets a boolean value indicating whether or not to take the epoch of the session -into account when dealing with re-applying ACL's or changing already applied ACL's. -Defaults to 0 (false), meaning the default implementation does NOT take the -epoch of the session into account. - -.. code-block:: console - - reclassify sessions 1 - -.. _api-queue: - -api-queue Section ------------------ - -length <n> -^^^^^^^^^^^ - -Sets the api queue length. Minimum valid queue length is 1024, which is -also the default. - -.. code-block:: console - - length 2048 - -.. _cj: - -cj Section ----------- - -The circular journal (CJ) thread-safe circular log buffer scheme is -occasionally useful when chasing bugs. Calls to it should not be checked in. -See .../vlib/vlib/unix/cj.c. The circular journal is disables by default. -When enabled, the number of records must be provided, there is no default -value. - -records <n> -^^^^^^^^^^^ - -Configure the number of circular journal records in the circular buffer. -The number of records should be a power of 2. - -.. code-block:: console - - records 131072 - -on -^^ - -Turns on logging at the earliest possible moment. - -.. code-block:: console - - on - -dns Section ------------ - -max-cache-size <n> -^^^^^^^^^^^^^^^^^^ - -Set the maximum number of active elements allowed in the pool of -dns cache entries. When resolving an expired entry or adding a new -static entry and the max number of active entries is reached, -a random, non-static entry is deleted. Defaults to 65535 entries. - -.. code-block:: console - - max-cache-size 65535 - - -ethernet Section ------------------ - -default-mtu <n> -^^^^^^^^^^^^^^^ - -Specifies the default MTU size for Ethernet interfaces. Must be in -the range of 64-9000. The default is 9000. - -.. code-block:: console - - default-mtu 1500 - -heapsize Section ------------------ - -Heapsize configuration controls the size of the main heap. The heap size is -configured very early in the boot sequence, before loading plug-ins or doing -much of anything else. - -heapsize <n>M | <n>G -^^^^^^^^^^^^^^^^^^^^ - -Specifies the size of the heap in MB or GB. The default is 1GB. - -.. code-block:: console - - heapsize 2G - -ip Section ----------- - -IPv4 heap configuration. he heap size is configured very early in the boot -sequence, before loading plug-ins or doing much of anything else. - -heap-size <n>G | <n>M | <n>K | <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Set the IPv4 mtrie heap size, which is the amount of memory dedicated to -the destination IP lookup table. The input value can be set in GB, MB, KB -or bytes. The default value is 32MB. - -.. code-block:: console - - heap-size 64M - -ip6 Section ------------ - -IPv6 heap configuration. he heap size is configured very early in the boot -sequence, before loading plug-ins or doing much of anything else. - - -heap-size <n>G | <n>M | <n>K | <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Set the IPv6 forwarding table heap size. The input value can be set in GB, -MB, KB or bytes. The default value is 32MB. - -.. code-block:: console - - heap-size 64M - -hash-buckets <n> -^^^^^^^^^^^^^^^^ - -Set the number of IPv6 forwarding table hash buckets. The default value is -64K (65536). - -.. code-block:: console - - hash-buckets 131072 - -l2learn Section ---------------- - -Configure Layer 2 MAC Address learning parameters. - -limit <n> -^^^^^^^^^ - -Configures the number of L2 (MAC) addresses in the L2 FIB at any one time, -which limits the size of the L2 FIB to <n> concurrent entries. Defaults to -4M entries (4194304). - -.. code-block:: console - - limit 8388608 - -l2tp Section ------------- - -IPv6 Layer 2 Tunnelling Protocol Version 3 (IPv6-L2TPv3) configuration controls -the method used to locate a specific IPv6-L2TPv3 tunnel. The following settings -are mutually exclusive: - -lookup-v6-src -^^^^^^^^^^^^^ - -Lookup tunnel by IPv6 source address. - -.. code-block:: console - - lookup-v6-src - -lookup-v6-dst -^^^^^^^^^^^^^ - -Lookup tunnel by IPv6 destination address. - -.. code-block:: console - - lookup-v6-dst - -lookup-session-id -^^^^^^^^^^^^^^^^^ - -Lookup tunnel by L2TPv3 session identifier. - -.. code-block:: console - - lookup-session-id - -logging Section ---------------- - -size <n> -^^^^^^^^ - -Number of entries in the global logging buffer. Defaults to 512. - -.. code-block:: console - - size 512 - -nthrottle-time <n> -^^^^^^^^^^^^^^^^^^ - -Set the global value for the time to wait (in seconds) before resuming -logging of a log subclass that exceeded the per-subclass message-per-second -threshold. Defaults to 3. - -.. code-block:: console - - unthrottle-time 3 - -default-log-level emerg|alert | crit | err | warn | notice | info | debug | disabled -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Set the default logging level of the system log. Defaults to notice. - -.. code-block:: console - - default-log-level notice - -default-syslog-log-level emerg|alert | crit | err | warn | notice | info | debug | disabled -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Set the default logging level of the syslog target. Defaults to warning. - -.. code-block:: console - - default-syslog-log-level warning - -mactime Section ---------------- - -lookup-table-buckets <n> -^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the number of hash buckets in the mactime bi-hash lookup table. -Defaults to 128 buckets. - -.. code-block:: console - - lookup-table-buckets 128 - -lookup-table-memory <n>G | <n>M | <n>K | <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the allocated memory size (in bytes) for the mactime bi-hash lookup table. -The input value can be set in GB, MB, KB or bytes. The default value is 262144 -(256 << 10) bytes or roughly 256KB. - -.. code-block:: console - - lookup-table-memory 300K - -timezone_offset <n> -^^^^^^^^^^^^^^^^^^^ - -Sets the timezone offset from UTC. Defaults to an offset of -5 hours -from UTC (US EST / EDT.) - -.. code-block:: console - - timezone_offset -5 - -"map" Parameters ----------------- - -customer edge -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets a boolean true to indicate that the MAP node is a Customer Edge (CE) -router. The boolean defaults to false, meaning the MAP node is not treated -as a CE router. - -.. code-block:: console - - customer edge - -nat Section ------------ - -These parameters change the configuration of the NAT (Network address translation) -plugin, such as how the NAT & NAT64 bi-hash tables are initialized, if the NAT is -endpoint dependent, or if the NAT is deterministic. - -For each NAT per thread data, the following 4 parameters change how certain -bi-hash tables are initialized. - -translation hash buckets <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the number of hash buckets in each of the two in/out NAT bi-hash lookup -tables. Defaults to 1024 buckets. - -If the NAT is indicated to be endpoint dependent, which can be set with the -:ref:`endpoint-dependent parameter <endpointLabel>`, then this parameter sets -the number of hash buckets in each of the two endpoint dependent sessions -NAT bi-hash lookup tables. - -.. code-block:: console - - translation hash buckets 1024 - -translation hash memory <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the allocated memory size (in bytes) for each of the two in/out NAT -bi-hash tables. Defaults to 134217728 (128 << 20) bytes, which is roughly 128 MB. - -If the NAT is indicated to be endpoint dependent, which can be set with the -:ref:`endpoint-dependent parameter <endpointLabel>`, then this parameter sets the -allocated memory size for each of the two endpoint dependent sessions NAT bi-hash -lookup tables. - -.. code-block:: console - - translation hash memory 134217728 - -user hash buckets <n> -^^^^^^^^^^^^^^^^^^^^^ - -Sets the number of hash buckets in the user bi-hash lookup table -(src address lookup for a user.) Defaults to 128 buckets. - -.. code-block:: console - - user hash buckets 128 - -user hash memory <n> -^^^^^^^^^^^^^^^^^^^^ - -Sets the allocated memory size (in bytes) for the user bi-hash lookup table -(src address lookup for a user.) Defaults to 67108864 (64 << 20) bytes, -which is roughly 64 MB. - -.. code-block:: console - - user hash memory 67108864 - -max translations per user <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the maximum amount of dynamic and/or static NAT sessions each user can have. -Defaults to 100. When this limit is reached, the least recently used translation -is recycled. - -.. code-block:: console - - max translations per user 50 - -deterministic -^^^^^^^^^^^^^ - -Sets a boolean value to 1 indicating that the NAT is deterministic. Defaults to 0, -meaning the NAT is not deterministic. - -.. code-block:: console - - deterministic - -nat64 bib hash buckets <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the number of hash buckets in each of the two in/out NAT64 BIB bi-hash -tables. Defaults to 1024 buckets. - -.. code-block:: console - - nat64 bib hash buckets 1024 - -nat64 bib hash memory <n> -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the allocated memory size (in bytes) for each of the two in/out NAT64 -BIB bi-hash tables. Defaults to 134217728 (128 << 20) bytes, -which is roughly 128 MB. - -.. code-block:: console - - nat64 bib hash memory 134217728 - -nat64 st hash buckets <n> -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the number of hash buckets in each of the two in/out NAT64 session table -bi-hash tables. Defaults to 2048 buckets. - -.. code-block:: console - - nat64 st hash buckets 2048 - -nat64 st hash memory <n> -^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the allocated memory size (in bytes) for each of the two in/out NAT64 session -table bi-hash tables. Defaults to 268435456 (256 << 20) bytes, which is roughly -256 MB. - -.. code-block:: console - - nat64 st hash memory 268435456 - -.. _endpointLabel: - -endpoint-dependent -^^^^^^^^^^^^^^^^^^ - -Sets a boolean value to 1, indicating that the NAT is endpoint dependent. -Defaults to 0, meaning the NAT is not endpoint dependent. - -.. code-block:: console - - endpoint-dependent - -oam Section ------------ - -OAM configuration controls the (ip4-icmp) interval, and number of misses -allowed before reporting an oam target down to any registered listener. - -interval <n.n> -^^^^^^^^^^^^^^ - -Interval, floating-point seconds, between sending OAM IPv4 ICMP messages. -Default is 2.04 seconds. - -.. code-block:: console - - interval 3.5 - -physmem Section ---------------- - -Configuration parameters used to specify base address and maximum size of -the memory allocated for the pmalloc module in VPP. pmalloc is a NUMA-aware, -growable physical memory allocator. pmalloc allocates memory for the DPDK -memory pool. - -base-addr <address> -^^^^^^^^^^^^^^^^^^^ - -Specify the base address for pmalloc memory space. - -.. code-block:: console - - base-addr 0xfffe00000000 - -max-size <n>G | <n>M | <n>K | <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Set the memory size for pmalloc memory space. The default is 16G. - -.. code-block:: console - - max-size 4G - -tapcli Section --------------- - -Configuration parameters for TAPCLI (dynamic tap interface hookup.) - -mtu <n> -^^^^^^^ - -Sets interface MTU (maximum transmission unit) size in bytes. This size -is also related to the number of MTU buffers. Defaults to 1500 bytes. - -.. code-block:: console - - mtu 1500 - -disable -^^^^^^^ - -Disables TAPCLI. Default is that TAPCLI is enabled. - -.. code-block:: console - - disable - - -tcp Section ------------ - -Configuration parameters for TCP host stack utilities. The following -preallocation parameters are related to the initialization of fixed-size, -preallocation pools. - -preallocated-connections <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the number of preallocated TCP connections. Defaults to 0. -The preallocated connections per thread is related to this value, -equal to (preallocated_connections / (num_threads - 1)). - -.. code-block:: console - - preallocated-connections 5 - -preallocated-half-open-connections <n> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the number of preallocated TCP half-open connections. Defaults to 0. - -.. code-block:: console - - preallocated-half-open-connections 5 - -buffer-fail-fraction <n.n> -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the TCP buffer fail fraction (a float) used for fault-injection -when debugging TCP buffer allocation. Its use is found in *tcp_debug.h*. -Defaults to 0.0. - -.. code-block:: console - - buffer-fail-fraction 0.0 - - -tls Section ------------ - -Configures TLS parameters, such as enabling the use of test certificates. -These parameters affect the tlsmbedtls and tlsopenssl plugins. - -use-test-cert-in-ca -^^^^^^^^^^^^^^^^^^^ - -Sets a boolean value to 1 to indicate during the initialization of a -TLS CA chain to attempt to parse and add test certificates to the chain. -Defaults to 0, meaning test certificates are not used. - -.. code-block:: console - - use-test-cert-in-ca - -ca-cert-path <filename> -^^^^^^^^^^^^^^^^^^^^^^^ - -Sets the filename path of the location of TLS CA certificates, used when -initializing and loading TLS CA certificates during the initialization -of a TLS CA chain. If not set, the default filename path is -*/etc/ssl/certs/ca-certificates.crt*. - -.. code-block:: console - - ca-cert-path /etc/ssl/certs/ca-certificates.crt - - -tuntap Section --------------- - -The "tuntap" driver configures a point-to-point interface between the vpp -engine and the local Linux kernel stack. This allows e.g. users to ssh to the -host | VM | container via vpp "revenue" interfaces. It's marginally useful, and -is currently disabled by default. To [dynamically] create TAP interfaces - the -preferred scheme - see the "tap_connect" binary API. The Linux network stack -"vnet" interface needs to manually configure, and VLAN and other settings if -desired. - - -enable|disable -^^^^^^^^^^^^^^ - -Enable or disable the tun/tap driver. - -.. code-block:: console - - enable - -ethernet|ether -^^^^^^^^^^^^^^ - -Create a tap device (ethernet MAC) instead of a tun device (point-to-point -tunnel). The two keywords are aliases for the same function. - -.. code-block:: console - - ethernet - -have-normal-interface|have-normal -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Treat the host Linux stack as a routing peer instead of programming VPP -interface L3 addresses onto the tun/tap devices. The two keywords are -aliases for the same function. - -.. code-block:: console - - have-normal-interface - -name <name> -^^^^^^^^^^^ - -Assign name to the tun/tap device. - -.. code-block:: console - - name vpp1 - - -vhost-user Section ------------------- - -Vhost-user configuration parameters control the vhost-user driver. - -coalesce-frames <n> -^^^^^^^^^^^^^^^^^^^ - -Subject to deadline-timer expiration - see next item - attempt to transmit -at least <n> packet frames. Default is 32 frames. - -.. code-block:: console - - coalesce-frames 64 - -coalesce-time <seconds> -^^^^^^^^^^^^^^^^^^^^^^^ - -Hold packets no longer than (floating-point) seconds before transmitting -them. Default is 0.001 seconds - -.. code-block:: console - - coalesce-time 0.002 - -dont-dump-memory -^^^^^^^^^^^^^^^^ - -vhost-user shared-memory segments can add up to a large amount of memory, so -it's handy to avoid adding them to corefiles when using a significant number -of such interfaces. - -.. code-block:: console - - dont-dump-memory - - -vlib Section ------------- - -These parameters configure VLIB, such as allowing you to choose whether to -enable memory traceback or a post-mortem elog dump. - -memory-trace -^^^^^^^^^^^^ - -Enables memory trace (mheap traceback.) Defaults to 0, meaning memory -trace is disabled. - -.. code-block:: console - - memory-trace - -elog-events <n> -^^^^^^^^^^^^^^^ - -Sets the number of elements/events (the size) of the event ring -(a circular buffer of events.) This number rounds to a power of 2. -Defaults to 131072 (128 << 10) elements. - -.. code-block:: console - - elog-events 4096 - -elog-post-mortem-dump -^^^^^^^^^^^^^^^^^^^^^ - -Enables the attempt of a post-mortem elog dump to -*/tmp/elog_post_mortem.<PID_OF_CALLING_PROCESS>* if os_panic or -os_exit is called. - -.. code-block:: console - - elog-post-mortem-dump |