blob: 69d6ee5e3ea51269bf50027cd3bfb0be0c141d7b [file] [log] [blame]
John DeNisco06dcd452018-07-26 12:45:10 -04001.. _startup:
2
John DeNisco4f859682019-12-10 14:25:50 -05003==========================================
4VPP Configuration - CLI and 'startup.conf'
5==========================================
John DeNisco06dcd452018-07-26 12:45:10 -04006
7After a successful installation, VPP installs a startup config file named
John DeNiscoc64ba6d2018-08-02 15:03:15 -04008*startup.conf* in the */etc/vpp/* directory. This file can be tailored to
John DeNisco06dcd452018-07-26 12:45:10 -04009make VPP run as desired, but contains default values for typical installations.
John DeNiscoc64ba6d2018-08-02 15:03:15 -040010
John DeNisco4f859682019-12-10 14:25:50 -050011Below are more details about this file and some of the the parameters and values
12it contains.
John DeNisco06dcd452018-07-26 12:45:10 -040013
14Command-line Arguments
15----------------------
16
John DeNisco4f859682019-12-10 14:25:50 -050017Before we describe details of the startup configuration file (startup.conf) it
18should be mentioned that VPP can be started without a startup configuration
19file.
20
John DeNisco06dcd452018-07-26 12:45:10 -040021Parameters are grouped by a section name. When providing more than one
22parameter to a section, all parameters for that section must be wrapped in
23curly braces. For example, to start VPP with configuration data via the
24command line with the section name *'unix'*:
25
26.. code-block:: console
27
28 $ sudo /usr/bin/vpp unix { interactive cli-listen 127.0.0.1:5002 }
29
30The command line can be presented as a single string or as several; anything
31given on the command line is concatenated with spaces into a single string
32before parsing. VPP applications must be able to locate their own executable
33images. The simplest way to ensure this will work is to invoke a VPP
34application by giving its absolute path. For example:
35*'/usr/bin/vpp <options>'* At startup, VPP applications parse through their
36own ELF-sections [primarily] to make lists of init, configuration, and exit
37handlers.
38
39When developing with VPP, in gdb it's often sufficient to start an application
40like this:
41
42.. code-block:: console
43
44 (gdb) run unix interactive
45
John DeNisco06dcd452018-07-26 12:45:10 -040046
John DeNisco4f859682019-12-10 14:25:50 -050047Startup Configuration File (startup.conf)
48-----------------------------------------
49
50The more typical way to specify the startup configuration to VPP is with the
51startup configuration file (startup.conf).
52
53The path of the file is provided to the VPP application on the command line.
54This is typically at /etc/vpp/startup.conf. If VPP is installed as a package
55a default startup.conf file is provided at this location.
56
57The format of the configuration file is a simple text file with the same content
58as the command line.
59
60**A very simple startup.conf file:**
John DeNisco06dcd452018-07-26 12:45:10 -040061
62.. code-block:: console
63
64 $ cat /etc/vpp/startup.conf
65 unix {
66 nodaemon
67 log /var/log/vpp/vpp.log
68 full-coredump
69 cli-listen localhost:5002
70 }
John DeNisco4f859682019-12-10 14:25:50 -050071
John DeNisco06dcd452018-07-26 12:45:10 -040072 api-trace {
73 on
74 }
John DeNisco4f859682019-12-10 14:25:50 -050075
John DeNisco06dcd452018-07-26 12:45:10 -040076 dpdk {
77 dev 0000:03:00.0
78 }
79
John DeNisco4f859682019-12-10 14:25:50 -050080VPP is instructed to load this file with the -c option. For example:
John DeNisco06dcd452018-07-26 12:45:10 -040081
82.. code-block:: console
83
84 $ sudo /usr/bin/vpp -c /etc/vpp/startup.conf
85
John DeNisco06dcd452018-07-26 12:45:10 -040086Configuration Parameters
87------------------------
88
John DeNisco4f859682019-12-10 14:25:50 -050089Below is the list of some section names and their associated parameters.
90This is not an exhaustive list, but should give you an idea of how VPP can be configured.
91
92For all of the configuration parameters search the source code for instances of
93**VLIB_CONFIG_FUNCTION** and **VLIB_EARLY_CONFIG_FUNCTION**.
John DeNisco06dcd452018-07-26 12:45:10 -040094
95For example, the invocation *'VLIB_CONFIG_FUNCTION (foo_config, "foo")'* will
96cause the function *'foo_config'* to receive all parameters given in a
John DeNisco4f859682019-12-10 14:25:50 -050097parameter block named "foo": "foo { arg1 arg2 arg3 ... }".
John DeNisco06dcd452018-07-26 12:45:10 -040098
John DeNisco4f859682019-12-10 14:25:50 -050099The unix section
100----------------
John DeNisco06dcd452018-07-26 12:45:10 -0400101
John DeNisco4f859682019-12-10 14:25:50 -0500102Configures VPP startup and behavior type attributes, as well and any OS based
John DeNisco06dcd452018-07-26 12:45:10 -0400103attributes.
104
John DeNisco4f859682019-12-10 14:25:50 -0500105.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -0400106
John DeNisco4f859682019-12-10 14:25:50 -0500107 unix {
108 nodaemon
109 log /var/log/vpp/vpp.log
110 full-coredump
111 cli-listen /run/vpp/cli.sock
112 gid vpp
113 }
114
115nodaemon
116^^^^^^^^
117
118Do not fork / background the vpp process. Typical when invoking VPP
119applications from a process monitor. Set by default in the default
120*'startup.conf'* file.
121
122.. code-block:: console
123
124 nodaemon
125
Ruslan Babayeve31820a2020-02-14 17:45:02 -0800126nosyslog
127^^^^^^^^
128
129Disable syslog and log errors to stderr instead. Typical when invoking
130VPP applications from a process monitor like runit or daemontools that
131pipe service's output to a dedicated log service, which will typically
132attach a timestamp and rotate the logs as necessary.
133
134.. code-block:: console
135
136 nosyslog
137
John DeNisco4f859682019-12-10 14:25:50 -0500138interactive
139^^^^^^^^^^^
140
141Attach CLI to stdin/out and provide a debugging command line interface.
142
143.. code-block:: console
144
145 interactive
146
147log <filename>
148^^^^^^^^^^^^^^
149
150Logs the startup configuration and all subsequent CLI commands in filename.
151Very useful in situations where folks don't remember or can't be bothered
152to include CLI commands in bug reports. The default *'startup.conf'* file
153is to write to *'/var/log/vpp/vpp.log'*.
154
155In VPP 18.04, the default log file location was moved from '/tmp/vpp.log'
156to '/var/log/vpp/vpp.log' . The VPP code is indifferent to the file location.
157However, if SELinux is enabled, then the new location is required for the file
158to be properly labeled. Check your local *'startup.conf'* file for the log file
159location on your system.
160
161.. code-block:: console
162
163 log /var/log/vpp/vpp-debug.log
164
165exec | startup-config <filename>
166^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
167
168Read startup operational configuration from filename. The contents of the file
169will be performed as though entered at the CLI. The two keywords are aliases
170for the same function; if both are specified, only the last will have an effect.
171
172A file of CLI commands might look like:
173
174.. code-block:: console
175
176 $ cat /usr/share/vpp/scripts/interface-up.txt
177 set interface state TenGigabitEthernet1/0/0 up
178 set interface state TenGigabitEthernet1/0/1 up
179
180Parameter Example:
181
182.. code-block:: console
183
184 startup-config /usr/share/vpp/scripts/interface-up.txt
185
186gid <number | name>
187^^^^^^^^^^^^^^^^^^^
188
189Sets the effective group ID to the input group ID or group name of the calling
190process.
191
192.. code-block:: console
193
194 gid vpp
195
196full-coredump
197^^^^^^^^^^^^^
198
199Ask the Linux kernel to dump all memory-mapped address regions, instead of
200just text+data+bss.
201
202.. code-block:: console
203
204 full-coredump
205
206coredump-size unlimited | <n>G | <n>M | <n>K | <n>
207^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
208
John DeNisco06dcd452018-07-26 12:45:10 -0400209 Set the maximum size of the coredump file. The input value can be set in
210 GB, MB, KB or bytes, or set to *'unlimited'*.
John DeNisco4f859682019-12-10 14:25:50 -0500211
212.. code-block:: console
213
214 coredump-size unlimited
215
216cli-listen <ipaddress:port> | <socket-path>
217^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
218
John DeNisco06dcd452018-07-26 12:45:10 -0400219 Bind the CLI to listen at address localhost on TCP port 5002. This will
220 accept an ipaddress:port pair or a filesystem path; in the latter case a
221 local Unix socket is opened instead. The default *'startup.conf'* file
222 is to open the socket *'/run/vpp/cli.sock'*.
John DeNisco4f859682019-12-10 14:25:50 -0500223
224.. code-block:: console
225
226 cli-listen localhost:5002
227 cli-listen /run/vpp/cli.sock
228
229cli-line-mode
230^^^^^^^^^^^^^
231
John DeNisco06dcd452018-07-26 12:45:10 -0400232 Disable character-by-character I/O on stdin. Useful when combined with,
233 for example, emacs M-x gud-gdb.
John DeNisco4f859682019-12-10 14:25:50 -0500234
235.. code-block:: console
236
237 cli-line-mode
238
239cli-prompt <string>
240^^^^^^^^^^^^^^^^^^^
241
John DeNisco06dcd452018-07-26 12:45:10 -0400242 Configure the CLI prompt to be string.
John DeNisco4f859682019-12-10 14:25:50 -0500243
244.. code-block:: console
245
246 cli-prompt vpp-2
247
248cli-history-limit <n>
249^^^^^^^^^^^^^^^^^^^^^
250
Paul Vinciguerra7fa3dd22019-10-27 17:28:10 -0400251 Limit command history to <n> lines. A value of 0 disables command history.
John DeNisco06dcd452018-07-26 12:45:10 -0400252 Default value: 50
John DeNisco4f859682019-12-10 14:25:50 -0500253
254.. code-block:: console
255
256 cli-history-limit 100
257
258cli-no-banner
259^^^^^^^^^^^^^
260
John DeNisco06dcd452018-07-26 12:45:10 -0400261 Disable the login banner on stdin and Telnet connections.
John DeNisco4f859682019-12-10 14:25:50 -0500262
263.. code-block:: console
264
265 cli-no-banner
266
267cli-no-pager
268^^^^^^^^^^^^
269
John DeNisco06dcd452018-07-26 12:45:10 -0400270 Disable the output pager.
John DeNisco4f859682019-12-10 14:25:50 -0500271
272.. code-block:: console
273
274 cli-no-pager
275
276cli-pager-buffer-limit <n>
277^^^^^^^^^^^^^^^^^^^^^^^^^^
278
John DeNisco06dcd452018-07-26 12:45:10 -0400279 Limit pager buffer to <n> lines of output. A value of 0 disables the
280 pager. Default value: 100000
John DeNisco4f859682019-12-10 14:25:50 -0500281
282.. code-block:: console
283
284 cli-pager-buffer-limit 5000
285
286runtime-dir <dir>
287^^^^^^^^^^^^^^^^^
288
John DeNisco06dcd452018-07-26 12:45:10 -0400289 Set the runtime directory, which is the default location for certain
290 files, like socket files. Default is based on User ID used to start VPP.
291 Typically it is *'root'*, which defaults to *'/run/vpp/'*. Otherwise,
292 defaults to *'/run/user/<uid>/vpp/'*.
John DeNisco06dcd452018-07-26 12:45:10 -0400293
294.. code-block:: console
295
John DeNisco4f859682019-12-10 14:25:50 -0500296 runtime-dir /tmp/vpp
297
298poll-sleep-usec <n>
299^^^^^^^^^^^^^^^^^^^
300
301 Add a fixed-sleep between main loop poll. Default is 0, which is not to
302 sleep.
303
304.. code-block:: console
305
306 poll-sleep-usec 100
307
308pidfile <filename>
309^^^^^^^^^^^^^^^^^^
310
311 Writes the pid of the main thread in the given filename.
312
313.. code-block:: console
314
315 pidfile /run/vpp/vpp1.pid
John DeNisco06dcd452018-07-26 12:45:10 -0400316
317
John DeNisco4f859682019-12-10 14:25:50 -0500318The api-trace Section
319---------------------
John DeNisco06dcd452018-07-26 12:45:10 -0400320
John DeNisco4f859682019-12-10 14:25:50 -0500321The ability to trace, dump, and replay control-plane API traces makes all the
322difference in the world when trying to understand what the control-plane has
323tried to ask the forwarding-plane to do.
324
325Typically, one simply enables the API message trace scheme:
326
327.. code-block:: console
328
329 api-trace {
330 api-trace on
331 }
332
333on | enable
334^^^^^^^^^^^
335
336 Enable API trace capture from the beginning of time, and arrange for a
337 post-mortem dump of the API trace if the application terminates abnormally.
338 By default, the (circular) trace buffer will be configured to capture
339 256K traces. The default *'startup.conf'* file has trace enabled by default,
340 and unless there is a very strong reason, it should remain enabled.
341
342.. code-block:: console
343
344 on
345
346nitems <n>
347^^^^^^^^^^
348
349 Configure the circular trace buffer to contain the last <n> entries. By
350 default, the trace buffer captures the last 256K API messages received.
351
352.. code-block:: console
353
354 nitems 524288
355
356save-api-table <filename>
357^^^^^^^^^^^^^^^^^^^^^^^^^
358
359 Dumps the API message table to /tmp/<filename>.
360
361.. code-block:: console
362
363 save-api-table apiTrace-07-04.txt
364
365
366The api-segment Section
367-----------------------
368
369These values control various aspects of the binary API interface to VPP.
370
371The default looks like the following:
372
373.. code-block:: console
374
375 api-segment {
376 gid vpp
377 }
378
379
380prefix <path>
381^^^^^^^^^^^^^
382
383 Sets the prefix prepended to the name used for shared memory (SHM)
384 segments. The default is empty, meaning shared memory segments are created
385 directly in the SHM directory *'/dev/shm'*. It is worth noting that on
386 many systems *'/dev/shm'* is a symbolic link to somewhere else in the file
387 system; Ubuntu links it to *'/run/shm'*.
388
389.. code-block:: console
390
391 prefix /run/shm
392
393uid <number | name>
394^^^^^^^^^^^^^^^^^^^
395
396 Sets the user ID or name that should be used to set the ownership of the
397 shared memory segments. Defaults to the same user that VPP is started
398 with, probably root.
399
400.. code-block:: console
401
402 uid root
403
404gid <number | name>
405^^^^^^^^^^^^^^^^^^^
406
407 Sets the group ID or name that should be used to set the ownership of the
408 shared memory segments. Defaults to the same group that VPP is started
409 with, probably root.
410
411.. code-block:: console
412
413 gid vpp
414
415**The following parameters should only be set by those that are familiar with the
416interworkings of VPP.**
417
418baseva <x>
419^^^^^^^^^^
420
421 Set the base address for SVM global region. If not set, on AArch64, the
422 code will try to determine the base address. All other default to
423 0x30000000.
424
425.. code-block:: console
426
427 baseva 0x20000000
428
429global-size <n>G | <n>M | <n>
430^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
431
432 Set the global memory size, memory shared across all router instances,
433 packet buffers, etc. If not set, defaults to 64M. The input value can be
434 set in GB, MB or bytes.
435
436.. code-block:: console
437
438 global-size 2G
439
440global-pvt-heap-size <n>M | size <n>
441^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
442
443 Set the size of the global VM private mheap. If not set, defaults to 128k.
444 The input value can be set in MB or bytes.
445
446.. code-block:: console
447
448 global-pvt-heap-size size 262144
449
450api-pvt-heap-size <n>M | size <n>
451^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
452
453 Set the size of the api private mheap. If not set, defaults to 128k.
454 The input value can be set in MB or bytes.
455
456.. code-block:: console
457
458 api-pvt-heap-size 1M
459
460api-size <n>M | <n>G | <n>
461^^^^^^^^^^^^^^^^^^^^^^^^^^
462
463 Set the size of the API region. If not set, defaults to 16M. The input
464 value can be set in GB, MB or bytes.
465
466.. code-block:: console
467
468 api-size 64M
469
470The socksvr Section
471-------------------
472
473Enables a Unix domain socket which processes binary API messages. See
474.../vlibmemory/socket_api.c. If this parameter is not set, vpp
475won't process binary API messages over sockets.
476
477.. code-block:: console
478
479 socksvr {
480 # Explicitly name a socket file
481 socket-name /run/vpp/api.sock
482 or
483 # Use defaults as described below
484 default
485 }
486
487The "default" keyword instructs vpp to use /run/vpp/api.sock when
488running as root, otherwise to use /run/user/<uid>/api.sock.
489
490The cpu Section
491---------------
492
493In the VPP there is one main thread and optionally the user can create worker(s)
494The main thread and worker thread(s) can be pinned to CPU core(s) manually or automatically
495
496.. code-block:: console
497
498 cpu {
499 main-core 1
500 corelist-workers 2-3,18-19
501 }
502
503
504Manual pinning of thread(s) to CPU core(s)
505^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
506
507main-core
508^^^^^^^^^
509
510Set logical CPU core where main thread runs, if main core is not set VPP will use
511core 1 if available
512
513.. code-block:: console
514
515 main-core 1
516
517corelist-workers
518^^^^^^^^^^^^^^^^
519
520Set logical CPU core(s) where worker threads are running
521
522.. code-block:: console
523
524 corelist-workers 2-3,18-19
525
526Automatic pinning of thread(s) to CPU core(s)
527^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
528
529skip-cores number
530^^^^^^^^^^^^^^^^^
531
532Sets number of CPU core(s) to be skipped (1 ... N-1), Skipped CPU core(s) are
533not used for pinning main thread and working thread(s).
534
535The main thread is automatically pinned to the first available CPU core and worker(s)
536are pinned to next free CPU core(s) after core assigned to main thread
537
538.. code-block:: console
539
540 skip-cores 4
541
542workers number
543^^^^^^^^^^^^^^
544
545Specify a number of workers to be created Workers are pinned to N consecutive
546CPU cores while skipping "skip-cores" CPU core(s) and main thread's CPU core
547
548.. code-block:: console
549
550 workers 2
551
552scheduler-policy other | batch | idle | fifo | rr
553^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
554
555Set scheduling policy and priority of main and worker threads
556
557Scheduling policy options are: other (SCHED_OTHER), batch (SCHED_BATCH)
558idle (SCHED_IDLE), fifo (SCHED_FIFO), rr (SCHED_RR)
559
560.. code-block:: console
561
562 scheduler-policy fifo
563
564scheduler-priority number
565^^^^^^^^^^^^^^^^^^^^^^^^^
566
567Scheduling priority is used only for "real-time policies (fifo and rr),
568and has to be in the range of priorities supported for a particular policy
569
570.. code-block:: console
571
572 scheduler-priority 50
573
574The buffers Section
575-------------------
576
577.. code-block:: console
578
579 buffers {
580 buffers-per-numa 128000
581 default data-size 2048
582 }
583
584buffers-per-numa number
585^^^^^^^^^^^^^^^^^^^^^^^
586
587Increase number of buffers allocated, needed only in scenarios with
588large number of interfaces and worker threads. Value is per numa node.
589Default is 16384 (8192 if running unpriviledged)
590
591.. code-block:: console
592
593 buffers-per-numa 128000
594
595default data-size number
596^^^^^^^^^^^^^^^^^^^^^^^^
597
598Size of buffer data area, default is 2048
599
600.. code-block:: console
601
602 default data-size 2048
603
604
605The dpdk Section
606----------------
607
608.. code-block:: console
609
610 dpdk {
611 dev default {
612 num-rx-desc 512
613 num-tx-desc 512
614 }
615
616 dev 0000:02:00.1 {
617 num-rx-queues 2
618 name eth0
619 }
620 }
621
622dev <pci-dev> | default { .. }
623^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
624
625White-list [as in, attempt to drive] a specific PCI device. PCI-dev is a
626string of the form "DDDD:BB:SS.F" where:
627
628* DDDD = Domain
629* BB = Bus Number
630* SS = Slot number
631* F = Function
632
Paul Vinciguerra5ac392d2020-03-01 01:37:37 -0500633If the keyword **default** is used the values will apply to all the devices.
John DeNisco4f859682019-12-10 14:25:50 -0500634
635This is the same format used in the linux sysfs tree (i.e./sys/bus/pci/devices)
636for PCI device directory names.
637
638.. code-block:: console
639
640 dpdk {
641 dev default {
642 num-rx-desc 512
643 num-tx-desc 512
644 }
645
646dev <pci-dev> { .. }
647^^^^^^^^^^^^^^^^^^^^
648
649Whitelist specific interface by specifying PCI address. When whitelisting specific
650interfaces by specifying PCI address, additional custom parameters can also be
651specified. Valid options include:
652
653.. code-block:: console
654
655 dev 0000:02:00.0
656 dev 0000:03:00.0
657
658blacklist <pci-dev>
659^^^^^^^^^^^^^^^^^^^
660
661Blacklist specific device type by specifying PCI vendor:device Whitelist entries
662take precedence
663
664.. code-block:: console
665
666 blacklist 8086:10fb
667
668name interface-name
669^^^^^^^^^^^^^^^^^^^
670
671Set interface name
672
673.. code-block:: console
674
675 dev 0000:02:00.1 {
676 name eth0
677 }
678
679num-rx-queues <n>
680^^^^^^^^^^^^^^^^^
681
682Number of receive queues. Also enables RSS. Default value is 1.
683
684.. code-block:: console
685
686 dev 0000:02:00.1 {
Paul Vinciguerra5ac392d2020-03-01 01:37:37 -0500687 num-rx-queues <n>
John DeNisco4f859682019-12-10 14:25:50 -0500688 }
689
690num-tx-queues <n>
691^^^^^^^^^^^^^^^^^
692
693Number of transmit queues. Default is equal to number of worker threads
694or 1 if no workers treads.
695
696.. code-block:: console
697
698 dev 000:02:00.1 {
699 num-tx-queues <n>
700 }
701
702num-rx-desc <n>
703^^^^^^^^^^^^^^^
704
705Number of descriptors in receive ring. Increasing or reducing number
706can impact performance. Default is 1024.
707
708.. code-block:: console
709
710 dev 000:02:00.1 {
711 num-rx-desc <n>
712 }
713
714vlan-strip-offload on | off
715^^^^^^^^^^^^^^^^^^^^^^^^^^^
716
717VLAN strip offload mode for interface. VLAN stripping is off by default
718for all NICs except VICs, using ENIC driver, which has VLAN stripping on
719by default.
720
721.. code-block:: console
722
723 dev 000:02:00.1 {
724 vlan-strip-offload on|off
725 }
726
727uio-driver driver-name
728^^^^^^^^^^^^^^^^^^^^^^
729
730Change UIO driver used by VPP, Options are: igb_uio, vfio-pci, uio_pci_generic
731or auto (default)
732
733
734.. code-block:: console
735
736 uio-driver vfio-pci
737
738no-multi-seg
739^^^^^^^^^^^^
740
741Disable multi-segment buffers, improves performance but disables Jumbo MTU support
742
743.. code-block:: console
744
745 no-multi-seg
746
747socket-mem <n>
748^^^^^^^^^^^^^^
749
750Change hugepages allocation per-socket, needed only if there is need for
751larger number of mbufs. Default is 256M on each detected CPU socket
752
753.. code-block:: console
754
755 socket-mem 2048,2048
756
757no-tx-checksum-offload
758^^^^^^^^^^^^^^^^^^^^^^
759
760Disables UDP / TCP TX checksum offload. Typically needed for use faster
761vector PMDs (together with no-multi-seg)
762
763.. code-block:: console
764
765 no-tx-checksum-offload
766
767enable-tcp-udp-checksum
768^^^^^^^^^^^^^^^^^^^^^^^
769
770Enable UDP / TCP TX checksum offload This is the reversed option of
771'no-tx-checksum-offload'
772
773.. code-block:: console
774
775 enable-tcp-udp-checksum
776
777The plugins Section
778-------------------
779
780Configure VPP plugins.
781
782.. code-block:: console
783
784 plugins {
785 path /ws/vpp/build-root/install-vpp-native/vpp/lib/vpp_plugins
786 plugin dpdk_plugin.so enable
787 }
788
789path pathname
790^^^^^^^^^^^^^
791
792Adjust the plugin path depending on where the VPP plugins are.
793
794.. code-block:: console
795
796 path /ws/vpp/build-root/install-vpp-native/vpp/lib/vpp_plugins
797
798plugin plugin-name | default enable | disable
799^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
800
801Disable all plugins by default and then selectively enable specific plugins
802
803.. code-block:: console
804
805 plugin default disable
806 plugin dpdk_plugin.so enable
807 plugin acl_plugin.so enable
808
809Enable all plugins by default and then selectively disable specific plugins
810
811.. code-block:: console
812
813 plugin dpdk_plugin.so disable
814 plugin acl_plugin.so disable
815
816Th statseg Section
817^^^^^^^^^^^^^^^^^^
818
819.. code-block:: console
820
821 statseg {
822 per-node-counters on
823 }
824
825socket-name <filename>
826^^^^^^^^^^^^^^^^^^^^^^
827
828Name of the stats segment socket defaults to /run/vpp/stats.sock.
829
830.. code-block:: console
831
832 socket-name /run/vpp/stats.sock
833
834size <nnn>[KMG]
835^^^^^^^^^^^^^^^
836
837The size of the stats segment, defaults to 32mb
838
839.. code-block:: console
840
841 size 1024M
842
843per-node-counters on | off
844^^^^^^^^^^^^^^^^^^^^^^^^^^
845
846Defaults to none
847
848.. code-block:: console
849
850 per-node-counters on
851
852update-interval <f64-seconds>
853^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
854
855Sets the segment scrape / update interval
856
857.. code-block:: console
858
859 update-interval 300
860
861
862Some Advanced Parameters:
863-------------------------
864
865
866acl-plugin Section
867------------------
John DeNisco06dcd452018-07-26 12:45:10 -0400868
andrew9f0c0202018-08-14 09:35:42 -0400869These parameters change the configuration of the ACL (access control list) plugin,
870such as how the ACL bi-hash tables are initialized.
John DeNisco06dcd452018-07-26 12:45:10 -0400871
andrew9f0c0202018-08-14 09:35:42 -0400872They should only be set by those that are familiar with the interworkings of VPP
873and the ACL Plugin.
874
875The first three parameters, *connection hash buckets*, *connection hash memory*,
876and *connection count max*, set the **connection table per-interface parameters**
877for modifying how the two bounded-index extensible hash tables for
878IPv6 (40\*8 bit key and 8\*8 bit value pairs) and IPv4
879(16\*8 bit key and 8\*8 bit value pairs) **ACL plugin FA interface sessions**
880are initialized.
John DeNisco06dcd452018-07-26 12:45:10 -0400881
John DeNisco4f859682019-12-10 14:25:50 -0500882connection hash buckets <n>
883^^^^^^^^^^^^^^^^^^^^^^^^^^^
884
885Sets the number of hash buckets (rounded up to a power of 2) in each
886of the two bi-hash tables. Defaults to 64\*1024 (65536) hash buckets.
887
888.. code-block:: console
889
890 connection hash buckets 65536
891
892connection hash memory <n>
893^^^^^^^^^^^^^^^^^^^^^^^^^^
894
895Sets the allocated memory size (in bytes) for each of the two bi-hash tables.
896Defaults to 1073741824 bytes.
897
898.. code-block:: console
899
900 connection hash memory 1073741824
901
902connection count max <n>
903^^^^^^^^^^^^^^^^^^^^^^^^
904
905Sets the maximum number of pool elements when allocating each per-worker
906pool of sessions for both bi-hash tables. Defaults to 500000 elements in each pool.
907
908.. code-block:: console
909
910 connection count max 500000
911
912main heap size <n>G | <n>M | <n>K | <n>
913^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
914
915Sets the size of the main memory heap that holds all the ACL module related
916allocations (other than hash.) Default size is 0, but during
917ACL heap initialization is equal to
918*per_worker_size_with_slack * tm->n_vlib_mains + bihash_size + main_slack*.
919Note that these variables are partially based on the
920**connection table per-interface parameters** mentioned above.
921
922.. code-block:: console
923
924 main heap size 3G
John DeNisco06dcd452018-07-26 12:45:10 -0400925
andrew9f0c0202018-08-14 09:35:42 -0400926The next three parameters, *hash lookup heap size*, *hash lookup hash buckets*,
927and *hash lookup hash memory*, modify the initialization of the bi-hash lookup
928table used by the ACL plugin. This table is initialized when attempting to apply
929an ACL to the existing vector of ACLs looked up during packet processing
930(but it is found that the table does not exist / has not been initialized yet.)
John DeNisco4f859682019-12-10 14:25:50 -0500931
932hash lookup heap size <n>G | <n>M | <n> K | <n>
933^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
934
935Sets the size of the memory heap that holds all the miscellaneous allocations
936related to hash-based lookups. Default size is 67108864 bytes.
937
938.. code-block:: console
939
940 hash lookup heap size 70M
941
942hash lookup hash buckets <n>
943^^^^^^^^^^^^^^^^^^^^^^^^^^^^
944
945Sets the number of hash buckets (rounded up to a power of 2) in the bi-hash
946lookup table. Defaults to 65536 hash buckets.
947
948.. code-block:: console
949
950 hash lookup hash buckets 65536
951
952hash lookup hash memory <n>
953^^^^^^^^^^^^^^^^^^^^^^^^^^^
954
955Sets the allocated memory size (in bytes) for the bi-hash lookup table.
956Defaults to 67108864 bytes.
957
958.. code-block:: console
959
960 hash lookup hash memory 67108864
961
962use tuple merge <n>
963^^^^^^^^^^^^^^^^^^^
964
965Sets a boolean value indicating whether or not to use TupleMerge
966for hash ACL's. Defaults to 1 (true), meaning the default implementation
967of hashing ACL's does use TupleMerge.
968
969.. code-block:: console
970
971 use tuple merge 1
972
973tuple merge split threshold <n>
974^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
975
976Sets the maximum amount of rules (ACE's) that can collide in a bi-hash
977lookup table before the table is split into two new tables. Splitting ensures
978less rule collisions by hashing colliding rules based on their common tuple
979(usually their maximum common tuple.) Splitting occurs when the
980*length of the colliding rules vector* is greater than this threshold amount.
981Defaults to a maximum of 39 rule collisions per table.
982
983.. code-block:: console
984
985 tuple merge split threshold 30
986
987reclassify sessions <n>
988^^^^^^^^^^^^^^^^^^^^^^^
989
990Sets a boolean value indicating whether or not to take the epoch of the session
991into account when dealing with re-applying ACL's or changing already applied ACL's.
992Defaults to 0 (false), meaning the default implementation does NOT take the
993epoch of the session into account.
994
995.. code-block:: console
996
997 reclassify sessions 1
John DeNisco06dcd452018-07-26 12:45:10 -0400998
999.. _api-queue:
1000
John DeNisco4f859682019-12-10 14:25:50 -05001001api-queue Section
1002-----------------
John DeNisco06dcd452018-07-26 12:45:10 -04001003
John DeNisco4f859682019-12-10 14:25:50 -05001004length <n>
1005^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001006
John DeNisco4f859682019-12-10 14:25:50 -05001007Sets the api queue length. Minimum valid queue length is 1024, which is
1008also the default.
John DeNisco06dcd452018-07-26 12:45:10 -04001009
John DeNisco4f859682019-12-10 14:25:50 -05001010.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -04001011
John DeNisco4f859682019-12-10 14:25:50 -05001012 length 2048
John DeNisco06dcd452018-07-26 12:45:10 -04001013
1014.. _cj:
1015
John DeNisco4f859682019-12-10 14:25:50 -05001016cj Section
1017----------
John DeNisco06dcd452018-07-26 12:45:10 -04001018
1019The circular journal (CJ) thread-safe circular log buffer scheme is
1020occasionally useful when chasing bugs. Calls to it should not be checked in.
1021See .../vlib/vlib/unix/cj.c. The circular journal is disables by default.
1022When enabled, the number of records must be provided, there is no default
1023value.
1024
John DeNisco4f859682019-12-10 14:25:50 -05001025records <n>
1026^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001027
John DeNisco4f859682019-12-10 14:25:50 -05001028Configure the number of circular journal records in the circular buffer.
1029The number of records should be a power of 2.
John DeNisco06dcd452018-07-26 12:45:10 -04001030
John DeNisco4f859682019-12-10 14:25:50 -05001031.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -04001032
John DeNisco4f859682019-12-10 14:25:50 -05001033 records 131072
John DeNisco06dcd452018-07-26 12:45:10 -04001034
John DeNisco4f859682019-12-10 14:25:50 -05001035on
1036^^
John DeNisco06dcd452018-07-26 12:45:10 -04001037
John DeNisco4f859682019-12-10 14:25:50 -05001038Turns on logging at the earliest possible moment.
John DeNisco06dcd452018-07-26 12:45:10 -04001039
John DeNisco4f859682019-12-10 14:25:50 -05001040.. code-block:: console
1041
1042 on
1043
1044dns Section
1045-----------
1046
1047max-cache-size <n>
1048^^^^^^^^^^^^^^^^^^
1049
1050Set the maximum number of active elements allowed in the pool of
1051dns cache entries. When resolving an expired entry or adding a new
1052static entry and the max number of active entries is reached,
1053a random, non-static entry is deleted. Defaults to 65535 entries.
1054
1055.. code-block:: console
1056
1057 max-cache-size 65535
1058
Paul Vinciguerra491741a2020-03-02 16:10:54 -05001059
1060ethernet Section
1061-----------------
1062
1063default-mtu <n>
1064^^^^^^^^^^^^^^^
1065
1066Specifies the default MTU size for Ethernet interfaces. Must be in
1067the range of 64-9000. The default is 9000.
1068
1069.. code-block:: console
1070
1071 default-mtu 1500
1072
John DeNisco4f859682019-12-10 14:25:50 -05001073heapsize Section
1074-----------------
John DeNisco06dcd452018-07-26 12:45:10 -04001075
1076Heapsize configuration controls the size of the main heap. The heap size is
1077configured very early in the boot sequence, before loading plug-ins or doing
1078much of anything else.
1079
John DeNisco4f859682019-12-10 14:25:50 -05001080heapsize <n>M | <n>G
1081^^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001082
Dave Barach2fef3df2020-02-21 17:31:17 -05001083Specifies the size of the heap in MB or GB. The default is 1GB.
John DeNisco06dcd452018-07-26 12:45:10 -04001084
John DeNisco4f859682019-12-10 14:25:50 -05001085.. code-block:: console
1086
1087 heapsize 2G
1088
1089ip Section
1090----------
John DeNisco06dcd452018-07-26 12:45:10 -04001091
1092IPv4 heap configuration. he heap size is configured very early in the boot
1093sequence, before loading plug-ins or doing much of anything else.
1094
John DeNisco4f859682019-12-10 14:25:50 -05001095heap-size <n>G | <n>M | <n>K | <n>
1096^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001097
John DeNisco4f859682019-12-10 14:25:50 -05001098Set the IPv4 mtrie heap size, which is the amount of memory dedicated to
1099the destination IP lookup table. The input value can be set in GB, MB, KB
1100or bytes. The default value is 32MB.
John DeNisco06dcd452018-07-26 12:45:10 -04001101
John DeNisco4f859682019-12-10 14:25:50 -05001102.. code-block:: console
1103
1104 heap-size 64M
1105
1106ip6 Section
1107-----------
John DeNisco06dcd452018-07-26 12:45:10 -04001108
1109IPv6 heap configuration. he heap size is configured very early in the boot
1110sequence, before loading plug-ins or doing much of anything else.
1111
1112
John DeNisco4f859682019-12-10 14:25:50 -05001113heap-size <n>G | <n>M | <n>K | <n>
1114^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001115
John DeNisco4f859682019-12-10 14:25:50 -05001116Set the IPv6 forwarding table heap size. The input value can be set in GB,
1117MB, KB or bytes. The default value is 32MB.
John DeNisco06dcd452018-07-26 12:45:10 -04001118
John DeNisco4f859682019-12-10 14:25:50 -05001119.. code-block:: console
1120
1121 heap-size 64M
1122
1123hash-buckets <n>
1124^^^^^^^^^^^^^^^^
1125
1126Set the number of IPv6 forwarding table hash buckets. The default value is
112764K (65536).
1128
1129.. code-block:: console
1130
1131 hash-buckets 131072
1132
1133l2learn Section
1134---------------
John DeNisco06dcd452018-07-26 12:45:10 -04001135
1136Configure Layer 2 MAC Address learning parameters.
1137
John DeNisco4f859682019-12-10 14:25:50 -05001138limit <n>
1139^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001140
John DeNisco4f859682019-12-10 14:25:50 -05001141Configures the number of L2 (MAC) addresses in the L2 FIB at any one time,
1142which limits the size of the L2 FIB to <n> concurrent entries. Defaults to
11434M entries (4194304).
John DeNisco06dcd452018-07-26 12:45:10 -04001144
John DeNisco4f859682019-12-10 14:25:50 -05001145.. code-block:: console
1146
1147 limit 8388608
1148
1149l2tp Section
1150------------
John DeNisco06dcd452018-07-26 12:45:10 -04001151
1152IPv6 Layer 2 Tunnelling Protocol Version 3 (IPv6-L2TPv3) configuration controls
1153the method used to locate a specific IPv6-L2TPv3 tunnel. The following settings
1154are mutually exclusive:
1155
John DeNisco4f859682019-12-10 14:25:50 -05001156lookup-v6-src
1157^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001158
John DeNisco4f859682019-12-10 14:25:50 -05001159Lookup tunnel by IPv6 source address.
John DeNisco06dcd452018-07-26 12:45:10 -04001160
John DeNisco4f859682019-12-10 14:25:50 -05001161.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -04001162
John DeNisco4f859682019-12-10 14:25:50 -05001163 lookup-v6-src
John DeNisco06dcd452018-07-26 12:45:10 -04001164
John DeNisco4f859682019-12-10 14:25:50 -05001165lookup-v6-dst
1166^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001167
John DeNisco4f859682019-12-10 14:25:50 -05001168Lookup tunnel by IPv6 destination address.
John DeNisco06dcd452018-07-26 12:45:10 -04001169
John DeNisco4f859682019-12-10 14:25:50 -05001170.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -04001171
John DeNisco4f859682019-12-10 14:25:50 -05001172 lookup-v6-dst
1173
1174lookup-session-id
1175^^^^^^^^^^^^^^^^^
1176
1177Lookup tunnel by L2TPv3 session identifier.
1178
1179.. code-block:: console
1180
1181 lookup-session-id
1182
1183logging Section
1184---------------
1185
1186size <n>
1187^^^^^^^^
1188
1189Number of entries in the global logging buffer. Defaults to 512.
1190
1191.. code-block:: console
1192
1193 size 512
1194
1195nthrottle-time <n>
1196^^^^^^^^^^^^^^^^^^
1197
1198Set the global value for the time to wait (in seconds) before resuming
1199logging of a log subclass that exceeded the per-subclass message-per-second
1200threshold. Defaults to 3.
1201
1202.. code-block:: console
1203
1204 unthrottle-time 3
1205
1206default-log-level emerg|alert | crit | err | warn | notice | info | debug | disabled
1207^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1208
1209Set the default logging level of the system log. Defaults to notice.
1210
1211.. code-block:: console
1212
1213 default-log-level notice
1214
1215default-syslog-log-level emerg|alert | crit | err | warn | notice | info | debug | disabled
1216^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1217
1218Set the default logging level of the syslog target. Defaults to warning.
1219
1220.. code-block:: console
1221
1222 default-syslog-log-level warning
1223
1224mactime Section
1225---------------
1226
1227lookup-table-buckets <n>
1228^^^^^^^^^^^^^^^^^^^^^^^^
1229
1230Sets the number of hash buckets in the mactime bi-hash lookup table.
1231Defaults to 128 buckets.
1232
1233.. code-block:: console
1234
1235 lookup-table-buckets 128
1236
1237lookup-table-memory <n>G | <n>M | <n>K | <n>
1238^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1239
1240Sets the allocated memory size (in bytes) for the mactime bi-hash lookup table.
1241The input value can be set in GB, MB, KB or bytes. The default value is 262144
1242(256 << 10) bytes or roughly 256KB.
1243
1244.. code-block:: console
1245
1246 lookup-table-memory 300K
1247
1248timezone_offset <n>
1249^^^^^^^^^^^^^^^^^^^
1250
1251Sets the timezone offset from UTC. Defaults to an offset of -5 hours
1252from UTC (US EST / EDT.)
1253
1254.. code-block:: console
1255
1256 timezone_offset -5
John DeNisco06dcd452018-07-26 12:45:10 -04001257
1258"map" Parameters
John DeNisco4f859682019-12-10 14:25:50 -05001259----------------
John DeNisco06dcd452018-07-26 12:45:10 -04001260
John DeNisco4f859682019-12-10 14:25:50 -05001261customer edge
1262^^^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001263
John DeNisco4f859682019-12-10 14:25:50 -05001264Sets a boolean true to indicate that the MAP node is a Customer Edge (CE)
1265router. The boolean defaults to false, meaning the MAP node is not treated
1266as a CE router.
John DeNisco06dcd452018-07-26 12:45:10 -04001267
John DeNisco4f859682019-12-10 14:25:50 -05001268.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -04001269
John DeNisco4f859682019-12-10 14:25:50 -05001270 customer edge
John DeNisco06dcd452018-07-26 12:45:10 -04001271
John DeNisco4f859682019-12-10 14:25:50 -05001272nat Section
1273-----------
John DeNisco06dcd452018-07-26 12:45:10 -04001274
andrew9f0c0202018-08-14 09:35:42 -04001275These parameters change the configuration of the NAT (Network address translation)
1276plugin, such as how the NAT & NAT64 bi-hash tables are initialized, if the NAT is
1277endpoint dependent, or if the NAT is deterministic.
1278
1279For each NAT per thread data, the following 4 parameters change how certain
1280bi-hash tables are initialized.
1281
John DeNisco4f859682019-12-10 14:25:50 -05001282translation hash buckets <n>
1283^^^^^^^^^^^^^^^^^^^^^^^^^^^^
andrew9f0c0202018-08-14 09:35:42 -04001284
John DeNisco4f859682019-12-10 14:25:50 -05001285Sets the number of hash buckets in each of the two in/out NAT bi-hash lookup
1286tables. Defaults to 1024 buckets.
andrew9f0c0202018-08-14 09:35:42 -04001287
John DeNisco4f859682019-12-10 14:25:50 -05001288If the NAT is indicated to be endpoint dependent, which can be set with the
1289:ref:`endpoint-dependent parameter <endpointLabel>`, then this parameter sets
1290the number of hash buckets in each of the two endpoint dependent sessions
1291NAT bi-hash lookup tables.
1292
1293.. code-block:: console
1294
1295 translation hash buckets 1024
1296
1297translation hash memory <n>
1298^^^^^^^^^^^^^^^^^^^^^^^^^^^
1299
1300Sets the allocated memory size (in bytes) for each of the two in/out NAT
1301bi-hash tables. Defaults to 134217728 (128 << 20) bytes, which is roughly 128 MB.
1302
1303If the NAT is indicated to be endpoint dependent, which can be set with the
1304:ref:`endpoint-dependent parameter <endpointLabel>`, then this parameter sets the
1305allocated memory size for each of the two endpoint dependent sessions NAT bi-hash
1306lookup tables.
1307
1308.. code-block:: console
1309
1310 translation hash memory 134217728
1311
1312user hash buckets <n>
1313^^^^^^^^^^^^^^^^^^^^^
1314
1315Sets the number of hash buckets in the user bi-hash lookup table
1316(src address lookup for a user.) Defaults to 128 buckets.
1317
1318.. code-block:: console
1319
1320 user hash buckets 128
1321
1322user hash memory <n>
1323^^^^^^^^^^^^^^^^^^^^
1324
1325Sets the allocated memory size (in bytes) for the user bi-hash lookup table
1326(src address lookup for a user.) Defaults to 67108864 (64 << 20) bytes,
1327which is roughly 64 MB.
1328
1329.. code-block:: console
1330
1331 user hash memory 67108864
1332
1333max translations per user <n>
1334^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1335
1336Sets the maximum amount of dynamic and/or static NAT sessions each user can have.
1337Defaults to 100. When this limit is reached, the least recently used translation
1338is recycled.
1339
1340.. code-block:: console
1341
1342 max translations per user 50
1343
1344deterministic
1345^^^^^^^^^^^^^
1346
1347Sets a boolean value to 1 indicating that the NAT is deterministic. Defaults to 0,
1348meaning the NAT is not deterministic.
1349
1350.. code-block:: console
1351
1352 deterministic
1353
1354nat64 bib hash buckets <n>
Jieqiang Wangaffa0552019-10-22 20:09:16 +08001355^^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco4f859682019-12-10 14:25:50 -05001356
1357Sets the number of hash buckets in each of the two in/out NAT64 BIB bi-hash
1358tables. Defaults to 1024 buckets.
1359
1360.. code-block:: console
1361
1362 nat64 bib hash buckets 1024
1363
1364nat64 bib hash memory <n>
Jieqiang Wangaffa0552019-10-22 20:09:16 +08001365^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco4f859682019-12-10 14:25:50 -05001366
1367Sets the allocated memory size (in bytes) for each of the two in/out NAT64
1368BIB bi-hash tables. Defaults to 134217728 (128 << 20) bytes,
1369which is roughly 128 MB.
1370
1371.. code-block:: console
1372
1373 nat64 bib hash memory 134217728
1374
1375nat64 st hash buckets <n>
Jieqiang Wangaffa0552019-10-22 20:09:16 +08001376^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco4f859682019-12-10 14:25:50 -05001377
1378Sets the number of hash buckets in each of the two in/out NAT64 session table
1379bi-hash tables. Defaults to 2048 buckets.
1380
1381.. code-block:: console
1382
1383 nat64 st hash buckets 2048
1384
1385nat64 st hash memory <n>
Jieqiang Wangaffa0552019-10-22 20:09:16 +08001386^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco4f859682019-12-10 14:25:50 -05001387
1388Sets the allocated memory size (in bytes) for each of the two in/out NAT64 session
1389table bi-hash tables. Defaults to 268435456 (256 << 20) bytes, which is roughly
1390256 MB.
1391
1392.. code-block:: console
1393
1394 nat64 st hash memory 268435456
1395
andrew9f0c0202018-08-14 09:35:42 -04001396.. _endpointLabel:
1397
John DeNisco4f859682019-12-10 14:25:50 -05001398endpoint-dependent
1399^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001400
John DeNisco4f859682019-12-10 14:25:50 -05001401Sets a boolean value to 1, indicating that the NAT is endpoint dependent.
1402Defaults to 0, meaning the NAT is not endpoint dependent.
John DeNisco06dcd452018-07-26 12:45:10 -04001403
John DeNisco4f859682019-12-10 14:25:50 -05001404.. code-block:: console
1405
1406 endpoint-dependent
1407
1408oam Section
1409-----------
John DeNisco06dcd452018-07-26 12:45:10 -04001410
1411OAM configuration controls the (ip4-icmp) interval, and number of misses
1412allowed before reporting an oam target down to any registered listener.
1413
John DeNisco4f859682019-12-10 14:25:50 -05001414interval <n.n>
1415^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001416
John DeNisco4f859682019-12-10 14:25:50 -05001417Interval, floating-point seconds, between sending OAM IPv4 ICMP messages.
1418Default is 2.04 seconds.
John DeNisco06dcd452018-07-26 12:45:10 -04001419
John DeNisco4f859682019-12-10 14:25:50 -05001420.. code-block:: console
andrew9f0c0202018-08-14 09:35:42 -04001421
John DeNisco4f859682019-12-10 14:25:50 -05001422 interval 3.5
John DeNisco06dcd452018-07-26 12:45:10 -04001423
Jieqiang Wangaffa0552019-10-22 20:09:16 +08001424physmem Section
1425---------------
1426
1427Configuration parameters used to specify base address and maximum size of
1428the memory allocated for the pmalloc module in VPP. pmalloc is a NUMA-aware,
1429growable physical memory allocator. pmalloc allocates memory for the DPDK
1430memory pool.
1431
1432base-addr <address>
1433^^^^^^^^^^^^^^^^^^^
1434
1435Specify the base address for pmalloc memory space.
1436
1437.. code-block:: console
1438
1439 base-addr 0xfffe00000000
1440
1441max-size <n>G | <n>M | <n>K | <n>
1442^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1443
1444Set the memory size for pmalloc memory space. The default is 16G.
1445
1446.. code-block:: console
1447
1448 max-size 4G
1449
John DeNisco4f859682019-12-10 14:25:50 -05001450tapcli Section
1451--------------
John DeNisco06dcd452018-07-26 12:45:10 -04001452
andrew9f0c0202018-08-14 09:35:42 -04001453Configuration parameters for TAPCLI (dynamic tap interface hookup.)
1454
John DeNisco4f859682019-12-10 14:25:50 -05001455mtu <n>
1456^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001457
John DeNisco4f859682019-12-10 14:25:50 -05001458Sets interface MTU (maximum transmission unit) size in bytes. This size
1459is also related to the number of MTU buffers. Defaults to 1500 bytes.
John DeNisco06dcd452018-07-26 12:45:10 -04001460
John DeNisco4f859682019-12-10 14:25:50 -05001461.. code-block:: console
1462
1463 mtu 1500
1464
1465disable
1466^^^^^^^
1467
1468Disables TAPCLI. Default is that TAPCLI is enabled.
1469
1470.. code-block:: console
1471
1472 disable
1473
1474
1475tcp Section
1476-----------
John DeNisco06dcd452018-07-26 12:45:10 -04001477
andrew9f0c0202018-08-14 09:35:42 -04001478Configuration parameters for TCP host stack utilities. The following
1479preallocation parameters are related to the initialization of fixed-size,
1480preallocation pools.
1481
John DeNisco4f859682019-12-10 14:25:50 -05001482preallocated-connections <n>
1483^^^^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001484
John DeNisco4f859682019-12-10 14:25:50 -05001485Sets the number of preallocated TCP connections. Defaults to 0.
1486The preallocated connections per thread is related to this value,
1487equal to (preallocated_connections / (num_threads - 1)).
John DeNisco06dcd452018-07-26 12:45:10 -04001488
John DeNisco4f859682019-12-10 14:25:50 -05001489.. code-block:: console
1490
1491 preallocated-connections 5
1492
1493preallocated-half-open-connections <n>
1494^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1495
1496Sets the number of preallocated TCP half-open connections. Defaults to 0.
1497
1498.. code-block:: console
1499
1500 preallocated-half-open-connections 5
1501
1502buffer-fail-fraction <n.n>
1503^^^^^^^^^^^^^^^^^^^^^^^^^^
1504
1505Sets the TCP buffer fail fraction (a float) used for fault-injection
1506when debugging TCP buffer allocation. Its use is found in *tcp_debug.h*.
1507Defaults to 0.0.
1508
1509.. code-block:: console
1510
1511 buffer-fail-fraction 0.0
1512
1513
1514tls Section
1515-----------
John DeNisco06dcd452018-07-26 12:45:10 -04001516
andrew9f0c0202018-08-14 09:35:42 -04001517Configures TLS parameters, such as enabling the use of test certificates.
1518These parameters affect the tlsmbedtls and tlsopenssl plugins.
1519
John DeNisco4f859682019-12-10 14:25:50 -05001520use-test-cert-in-ca
1521^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001522
John DeNisco4f859682019-12-10 14:25:50 -05001523Sets a boolean value to 1 to indicate during the initialization of a
1524TLS CA chain to attempt to parse and add test certificates to the chain.
1525Defaults to 0, meaning test certificates are not used.
John DeNisco06dcd452018-07-26 12:45:10 -04001526
John DeNisco4f859682019-12-10 14:25:50 -05001527.. code-block:: console
1528
1529 use-test-cert-in-ca
1530
1531ca-cert-path <filename>
1532^^^^^^^^^^^^^^^^^^^^^^^
1533
1534Sets the filename path of the location of TLS CA certificates, used when
1535initializing and loading TLS CA certificates during the initialization
1536of a TLS CA chain. If not set, the default filename path is
1537*/etc/ssl/certs/ca-certificates.crt*.
1538
1539.. code-block:: console
1540
1541 ca-cert-path /etc/ssl/certs/ca-certificates.crt
1542
1543
1544tuntap Section
1545--------------
John DeNisco06dcd452018-07-26 12:45:10 -04001546
1547The "tuntap" driver configures a point-to-point interface between the vpp
1548engine and the local Linux kernel stack. This allows e.g. users to ssh to the
1549host | VM | container via vpp "revenue" interfaces. It's marginally useful, and
1550is currently disabled by default. To [dynamically] create TAP interfaces - the
1551preferred scheme - see the "tap_connect" binary API. The Linux network stack
1552"vnet" interface needs to manually configure, and VLAN and other settings if
1553desired.
1554
John DeNisco06dcd452018-07-26 12:45:10 -04001555
John DeNisco4f859682019-12-10 14:25:50 -05001556enable|disable
1557^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001558
John DeNisco4f859682019-12-10 14:25:50 -05001559Enable or disable the tun/tap driver.
John DeNisco06dcd452018-07-26 12:45:10 -04001560
John DeNisco4f859682019-12-10 14:25:50 -05001561.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -04001562
John DeNisco4f859682019-12-10 14:25:50 -05001563 enable
1564
1565ethernet|ether
1566^^^^^^^^^^^^^^
1567
1568Create a tap device (ethernet MAC) instead of a tun device (point-to-point
1569tunnel). The two keywords are aliases for the same function.
1570
1571.. code-block:: console
1572
1573 ethernet
1574
1575have-normal-interface|have-normal
1576^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1577
1578Treat the host Linux stack as a routing peer instead of programming VPP
1579interface L3 addresses onto the tun/tap devices. The two keywords are
1580aliases for the same function.
1581
1582.. code-block:: console
1583
1584 have-normal-interface
1585
1586name <name>
1587^^^^^^^^^^^
1588
1589Assign name to the tun/tap device.
1590
1591.. code-block:: console
1592
1593 name vpp1
1594
1595
1596vhost-user Section
1597------------------
John DeNisco06dcd452018-07-26 12:45:10 -04001598
1599Vhost-user configuration parameters control the vhost-user driver.
1600
John DeNisco4f859682019-12-10 14:25:50 -05001601coalesce-frames <n>
1602^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001603
John DeNisco4f859682019-12-10 14:25:50 -05001604Subject to deadline-timer expiration - see next item - attempt to transmit
1605at least <n> packet frames. Default is 32 frames.
John DeNisco06dcd452018-07-26 12:45:10 -04001606
John DeNisco4f859682019-12-10 14:25:50 -05001607.. code-block:: console
1608
1609 coalesce-frames 64
1610
1611coalesce-time <seconds>
1612^^^^^^^^^^^^^^^^^^^^^^^
1613
1614Hold packets no longer than (floating-point) seconds before transmitting
1615them. Default is 0.001 seconds
1616
1617.. code-block:: console
1618
1619 coalesce-time 0.002
1620
1621dont-dump-memory
1622^^^^^^^^^^^^^^^^
1623
1624vhost-user shared-memory segments can add up to a large amount of memory, so
1625it's handy to avoid adding them to corefiles when using a significant number
1626of such interfaces.
1627
1628.. code-block:: console
1629
1630 dont-dump-memory
1631
1632
1633vlib Section
1634------------
John DeNisco06dcd452018-07-26 12:45:10 -04001635
andrew9f0c0202018-08-14 09:35:42 -04001636These parameters configure VLIB, such as allowing you to choose whether to
1637enable memory traceback or a post-mortem elog dump.
1638
John DeNisco4f859682019-12-10 14:25:50 -05001639memory-trace
1640^^^^^^^^^^^^
1641
1642Enables memory trace (mheap traceback.) Defaults to 0, meaning memory
1643trace is disabled.
1644
1645.. code-block:: console
1646
1647 memory-trace
1648
1649elog-events <n>
1650^^^^^^^^^^^^^^^
1651
1652Sets the number of elements/events (the size) of the event ring
1653(a circular buffer of events.) This number rounds to a power of 2.
1654Defaults to 131072 (128 << 10) elements.
1655
1656.. code-block:: console
1657
1658 elog-events 4096
1659
1660elog-post-mortem-dump
1661^^^^^^^^^^^^^^^^^^^^^
1662
1663Enables the attempt of a post-mortem elog dump to
1664*/tmp/elog_post_mortem.<PID_OF_CALLING_PROCESS>* if os_panic or
1665os_exit is called.
1666
1667.. code-block:: console
1668
1669 elog-post-mortem-dump