blob: 2a7726cccb499b25069f21a376be3c54ec34b66f [file] [log] [blame]
Nathan Skrzypczak9ad39c02021-08-19 11:38:06 +02001.. _configuration_reference:
John DeNisco06dcd452018-07-26 12:45:10 -04002
Nathan Skrzypczak9ad39c02021-08-19 11:38:06 +02003Configuration Reference
4=======================
John DeNisco06dcd452018-07-26 12:45:10 -04005
John DeNisco4f859682019-12-10 14:25:50 -05006Below is the list of some section names and their associated parameters.
7This is not an exhaustive list, but should give you an idea of how VPP can be configured.
8
9For all of the configuration parameters search the source code for instances of
10**VLIB_CONFIG_FUNCTION** and **VLIB_EARLY_CONFIG_FUNCTION**.
John DeNisco06dcd452018-07-26 12:45:10 -040011
12For example, the invocation *'VLIB_CONFIG_FUNCTION (foo_config, "foo")'* will
13cause the function *'foo_config'* to receive all parameters given in a
John DeNisco4f859682019-12-10 14:25:50 -050014parameter block named "foo": "foo { arg1 arg2 arg3 ... }".
John DeNisco06dcd452018-07-26 12:45:10 -040015
John DeNisco4f859682019-12-10 14:25:50 -050016The unix section
17----------------
John DeNisco06dcd452018-07-26 12:45:10 -040018
John DeNisco4f859682019-12-10 14:25:50 -050019Configures VPP startup and behavior type attributes, as well and any OS based
John DeNisco06dcd452018-07-26 12:45:10 -040020attributes.
21
John DeNisco4f859682019-12-10 14:25:50 -050022.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -040023
John DeNisco4f859682019-12-10 14:25:50 -050024 unix {
25 nodaemon
26 log /var/log/vpp/vpp.log
27 full-coredump
28 cli-listen /run/vpp/cli.sock
29 gid vpp
30 }
31
32nodaemon
33^^^^^^^^
34
35Do not fork / background the vpp process. Typical when invoking VPP
36applications from a process monitor. Set by default in the default
37*'startup.conf'* file.
38
39.. code-block:: console
40
41 nodaemon
42
Ruslan Babayeve31820a2020-02-14 17:45:02 -080043nosyslog
44^^^^^^^^
45
46Disable syslog and log errors to stderr instead. Typical when invoking
47VPP applications from a process monitor like runit or daemontools that
48pipe service's output to a dedicated log service, which will typically
49attach a timestamp and rotate the logs as necessary.
50
51.. code-block:: console
52
53 nosyslog
54
John DeNisco4f859682019-12-10 14:25:50 -050055interactive
56^^^^^^^^^^^
57
58Attach CLI to stdin/out and provide a debugging command line interface.
59
60.. code-block:: console
61
62 interactive
63
64log <filename>
65^^^^^^^^^^^^^^
66
67Logs the startup configuration and all subsequent CLI commands in filename.
68Very useful in situations where folks don't remember or can't be bothered
69to include CLI commands in bug reports. The default *'startup.conf'* file
70is to write to *'/var/log/vpp/vpp.log'*.
71
72In VPP 18.04, the default log file location was moved from '/tmp/vpp.log'
73to '/var/log/vpp/vpp.log' . The VPP code is indifferent to the file location.
74However, if SELinux is enabled, then the new location is required for the file
75to be properly labeled. Check your local *'startup.conf'* file for the log file
76location on your system.
77
78.. code-block:: console
79
80 log /var/log/vpp/vpp-debug.log
81
82exec | startup-config <filename>
83^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
84
85Read startup operational configuration from filename. The contents of the file
86will be performed as though entered at the CLI. The two keywords are aliases
87for the same function; if both are specified, only the last will have an effect.
88
89A file of CLI commands might look like:
90
91.. code-block:: console
92
93 $ cat /usr/share/vpp/scripts/interface-up.txt
94 set interface state TenGigabitEthernet1/0/0 up
95 set interface state TenGigabitEthernet1/0/1 up
96
97Parameter Example:
98
99.. code-block:: console
100
101 startup-config /usr/share/vpp/scripts/interface-up.txt
102
103gid <number | name>
104^^^^^^^^^^^^^^^^^^^
105
106Sets the effective group ID to the input group ID or group name of the calling
107process.
108
109.. code-block:: console
110
111 gid vpp
112
113full-coredump
114^^^^^^^^^^^^^
115
116Ask the Linux kernel to dump all memory-mapped address regions, instead of
117just text+data+bss.
118
119.. code-block:: console
120
121 full-coredump
122
123coredump-size unlimited | <n>G | <n>M | <n>K | <n>
124^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
125
John DeNisco06dcd452018-07-26 12:45:10 -0400126 Set the maximum size of the coredump file. The input value can be set in
127 GB, MB, KB or bytes, or set to *'unlimited'*.
John DeNisco4f859682019-12-10 14:25:50 -0500128
129.. code-block:: console
130
131 coredump-size unlimited
132
133cli-listen <ipaddress:port> | <socket-path>
134^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
135
John DeNisco06dcd452018-07-26 12:45:10 -0400136 Bind the CLI to listen at address localhost on TCP port 5002. This will
137 accept an ipaddress:port pair or a filesystem path; in the latter case a
138 local Unix socket is opened instead. The default *'startup.conf'* file
139 is to open the socket *'/run/vpp/cli.sock'*.
John DeNisco4f859682019-12-10 14:25:50 -0500140
141.. code-block:: console
142
143 cli-listen localhost:5002
144 cli-listen /run/vpp/cli.sock
145
146cli-line-mode
147^^^^^^^^^^^^^
148
John DeNisco06dcd452018-07-26 12:45:10 -0400149 Disable character-by-character I/O on stdin. Useful when combined with,
150 for example, emacs M-x gud-gdb.
John DeNisco4f859682019-12-10 14:25:50 -0500151
152.. code-block:: console
153
154 cli-line-mode
155
156cli-prompt <string>
157^^^^^^^^^^^^^^^^^^^
158
John DeNisco06dcd452018-07-26 12:45:10 -0400159 Configure the CLI prompt to be string.
John DeNisco4f859682019-12-10 14:25:50 -0500160
161.. code-block:: console
162
163 cli-prompt vpp-2
164
165cli-history-limit <n>
166^^^^^^^^^^^^^^^^^^^^^
167
Paul Vinciguerra7fa3dd22019-10-27 17:28:10 -0400168 Limit command history to <n> lines. A value of 0 disables command history.
John DeNisco06dcd452018-07-26 12:45:10 -0400169 Default value: 50
John DeNisco4f859682019-12-10 14:25:50 -0500170
171.. code-block:: console
172
173 cli-history-limit 100
174
175cli-no-banner
176^^^^^^^^^^^^^
177
John DeNisco06dcd452018-07-26 12:45:10 -0400178 Disable the login banner on stdin and Telnet connections.
John DeNisco4f859682019-12-10 14:25:50 -0500179
180.. code-block:: console
181
182 cli-no-banner
183
184cli-no-pager
185^^^^^^^^^^^^
186
John DeNisco06dcd452018-07-26 12:45:10 -0400187 Disable the output pager.
John DeNisco4f859682019-12-10 14:25:50 -0500188
189.. code-block:: console
190
191 cli-no-pager
192
193cli-pager-buffer-limit <n>
194^^^^^^^^^^^^^^^^^^^^^^^^^^
195
John DeNisco06dcd452018-07-26 12:45:10 -0400196 Limit pager buffer to <n> lines of output. A value of 0 disables the
197 pager. Default value: 100000
John DeNisco4f859682019-12-10 14:25:50 -0500198
199.. code-block:: console
200
201 cli-pager-buffer-limit 5000
202
203runtime-dir <dir>
204^^^^^^^^^^^^^^^^^
205
John DeNisco06dcd452018-07-26 12:45:10 -0400206 Set the runtime directory, which is the default location for certain
207 files, like socket files. Default is based on User ID used to start VPP.
208 Typically it is *'root'*, which defaults to *'/run/vpp/'*. Otherwise,
209 defaults to *'/run/user/<uid>/vpp/'*.
John DeNisco06dcd452018-07-26 12:45:10 -0400210
211.. code-block:: console
212
John DeNisco4f859682019-12-10 14:25:50 -0500213 runtime-dir /tmp/vpp
214
215poll-sleep-usec <n>
216^^^^^^^^^^^^^^^^^^^
217
218 Add a fixed-sleep between main loop poll. Default is 0, which is not to
219 sleep.
220
221.. code-block:: console
222
223 poll-sleep-usec 100
224
225pidfile <filename>
226^^^^^^^^^^^^^^^^^^
227
228 Writes the pid of the main thread in the given filename.
229
230.. code-block:: console
231
232 pidfile /run/vpp/vpp1.pid
John DeNisco06dcd452018-07-26 12:45:10 -0400233
234
John DeNisco4f859682019-12-10 14:25:50 -0500235The api-trace Section
236---------------------
John DeNisco06dcd452018-07-26 12:45:10 -0400237
John DeNisco4f859682019-12-10 14:25:50 -0500238The ability to trace, dump, and replay control-plane API traces makes all the
239difference in the world when trying to understand what the control-plane has
240tried to ask the forwarding-plane to do.
241
242Typically, one simply enables the API message trace scheme:
243
244.. code-block:: console
245
246 api-trace {
247 api-trace on
248 }
249
250on | enable
251^^^^^^^^^^^
252
253 Enable API trace capture from the beginning of time, and arrange for a
254 post-mortem dump of the API trace if the application terminates abnormally.
255 By default, the (circular) trace buffer will be configured to capture
256 256K traces. The default *'startup.conf'* file has trace enabled by default,
257 and unless there is a very strong reason, it should remain enabled.
258
259.. code-block:: console
260
261 on
262
263nitems <n>
264^^^^^^^^^^
265
266 Configure the circular trace buffer to contain the last <n> entries. By
267 default, the trace buffer captures the last 256K API messages received.
268
269.. code-block:: console
270
271 nitems 524288
272
273save-api-table <filename>
274^^^^^^^^^^^^^^^^^^^^^^^^^
275
276 Dumps the API message table to /tmp/<filename>.
277
278.. code-block:: console
279
280 save-api-table apiTrace-07-04.txt
281
282
283The api-segment Section
284-----------------------
285
286These values control various aspects of the binary API interface to VPP.
287
288The default looks like the following:
289
290.. code-block:: console
291
292 api-segment {
293 gid vpp
294 }
295
296
297prefix <path>
298^^^^^^^^^^^^^
299
300 Sets the prefix prepended to the name used for shared memory (SHM)
301 segments. The default is empty, meaning shared memory segments are created
302 directly in the SHM directory *'/dev/shm'*. It is worth noting that on
303 many systems *'/dev/shm'* is a symbolic link to somewhere else in the file
304 system; Ubuntu links it to *'/run/shm'*.
305
306.. code-block:: console
307
308 prefix /run/shm
309
310uid <number | name>
311^^^^^^^^^^^^^^^^^^^
312
313 Sets the user ID or name that should be used to set the ownership of the
314 shared memory segments. Defaults to the same user that VPP is started
315 with, probably root.
316
317.. code-block:: console
318
319 uid root
320
321gid <number | name>
322^^^^^^^^^^^^^^^^^^^
323
324 Sets the group ID or name that should be used to set the ownership of the
325 shared memory segments. Defaults to the same group that VPP is started
326 with, probably root.
327
328.. code-block:: console
329
330 gid vpp
331
332**The following parameters should only be set by those that are familiar with the
333interworkings of VPP.**
334
335baseva <x>
336^^^^^^^^^^
337
338 Set the base address for SVM global region. If not set, on AArch64, the
339 code will try to determine the base address. All other default to
340 0x30000000.
341
342.. code-block:: console
343
344 baseva 0x20000000
345
346global-size <n>G | <n>M | <n>
347^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
348
349 Set the global memory size, memory shared across all router instances,
350 packet buffers, etc. If not set, defaults to 64M. The input value can be
351 set in GB, MB or bytes.
352
353.. code-block:: console
354
355 global-size 2G
356
357global-pvt-heap-size <n>M | size <n>
358^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
359
360 Set the size of the global VM private mheap. If not set, defaults to 128k.
361 The input value can be set in MB or bytes.
362
363.. code-block:: console
364
365 global-pvt-heap-size size 262144
366
367api-pvt-heap-size <n>M | size <n>
368^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
369
370 Set the size of the api private mheap. If not set, defaults to 128k.
371 The input value can be set in MB or bytes.
372
373.. code-block:: console
374
375 api-pvt-heap-size 1M
376
377api-size <n>M | <n>G | <n>
378^^^^^^^^^^^^^^^^^^^^^^^^^^
379
380 Set the size of the API region. If not set, defaults to 16M. The input
381 value can be set in GB, MB or bytes.
382
383.. code-block:: console
384
385 api-size 64M
386
387The socksvr Section
388-------------------
389
390Enables a Unix domain socket which processes binary API messages. See
391.../vlibmemory/socket_api.c. If this parameter is not set, vpp
392won't process binary API messages over sockets.
393
394.. code-block:: console
395
396 socksvr {
397 # Explicitly name a socket file
398 socket-name /run/vpp/api.sock
399 or
400 # Use defaults as described below
401 default
402 }
403
404The "default" keyword instructs vpp to use /run/vpp/api.sock when
405running as root, otherwise to use /run/user/<uid>/api.sock.
406
407The cpu Section
408---------------
409
410In the VPP there is one main thread and optionally the user can create worker(s)
411The main thread and worker thread(s) can be pinned to CPU core(s) manually or automatically
412
413.. code-block:: console
414
415 cpu {
416 main-core 1
417 corelist-workers 2-3,18-19
418 }
419
420
421Manual pinning of thread(s) to CPU core(s)
422^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
423
424main-core
425^^^^^^^^^
426
427Set logical CPU core where main thread runs, if main core is not set VPP will use
428core 1 if available
429
430.. code-block:: console
431
432 main-core 1
433
434corelist-workers
435^^^^^^^^^^^^^^^^
436
437Set logical CPU core(s) where worker threads are running
438
439.. code-block:: console
440
441 corelist-workers 2-3,18-19
442
443Automatic pinning of thread(s) to CPU core(s)
444^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
445
446skip-cores number
447^^^^^^^^^^^^^^^^^
448
449Sets number of CPU core(s) to be skipped (1 ... N-1), Skipped CPU core(s) are
450not used for pinning main thread and working thread(s).
451
452The main thread is automatically pinned to the first available CPU core and worker(s)
453are pinned to next free CPU core(s) after core assigned to main thread
454
455.. code-block:: console
456
457 skip-cores 4
458
459workers number
460^^^^^^^^^^^^^^
461
462Specify a number of workers to be created Workers are pinned to N consecutive
463CPU cores while skipping "skip-cores" CPU core(s) and main thread's CPU core
464
465.. code-block:: console
466
467 workers 2
468
469scheduler-policy other | batch | idle | fifo | rr
470^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
471
472Set scheduling policy and priority of main and worker threads
473
474Scheduling policy options are: other (SCHED_OTHER), batch (SCHED_BATCH)
475idle (SCHED_IDLE), fifo (SCHED_FIFO), rr (SCHED_RR)
476
477.. code-block:: console
478
479 scheduler-policy fifo
480
481scheduler-priority number
482^^^^^^^^^^^^^^^^^^^^^^^^^
483
484Scheduling priority is used only for "real-time policies (fifo and rr),
485and has to be in the range of priorities supported for a particular policy
486
487.. code-block:: console
488
489 scheduler-priority 50
490
491The buffers Section
492-------------------
493
494.. code-block:: console
495
496 buffers {
497 buffers-per-numa 128000
498 default data-size 2048
Nathan Skrzypczak61559022020-11-23 16:25:21 +0100499 page-size default-hugepage
Lukas Stockner63ff7a62024-06-04 16:14:55 +0200500 numa 1 {
501 buffers 64000
502 }
John DeNisco4f859682019-12-10 14:25:50 -0500503 }
504
505buffers-per-numa number
506^^^^^^^^^^^^^^^^^^^^^^^
507
508Increase number of buffers allocated, needed only in scenarios with
509large number of interfaces and worker threads. Value is per numa node.
Nathan Skrzypczak9ad39c02021-08-19 11:38:06 +0200510Default is 16384 (8192 if running unprivileged)
John DeNisco4f859682019-12-10 14:25:50 -0500511
512.. code-block:: console
513
514 buffers-per-numa 128000
515
516default data-size number
517^^^^^^^^^^^^^^^^^^^^^^^^
518
519Size of buffer data area, default is 2048
520
521.. code-block:: console
522
523 default data-size 2048
524
Nathan Skrzypczak61559022020-11-23 16:25:21 +0100525page-size number
526^^^^^^^^^^^^^^^^
527
528Set the page size for buffer allocation
529
530.. code-block:: console
531
532 page-size 4K
533 page-size 2M
534 page-size 1G
535 page-size default
536 page-size default-hugepage
537
Lukas Stockner63ff7a62024-06-04 16:14:55 +0200538numa <numa index> { .. }
539^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
540
541Settings specific to a single NUMA domain.
542
543.. code-block:: console
544
545 buffers {
546 numa 0 {
547 buffers 32768
548 }
549 }
550
551buffers <n>
552^^^^^^^^^^^^^^^
553
554The number of buffers allocated for this specific NUMA domain.
Lukas Stocknerb4808de2024-06-18 14:52:52 +0200555If this is set to zero, no buffers are allocated for this domain.
556
557By default, the value configured in **buffers-per-numa** is used.
Lukas Stockner63ff7a62024-06-04 16:14:55 +0200558
559.. code-block:: console
560
561 numa 0 {
562 buffers 32768
563 }
564
John DeNisco4f859682019-12-10 14:25:50 -0500565
566The dpdk Section
567----------------
568
569.. code-block:: console
570
571 dpdk {
572 dev default {
573 num-rx-desc 512
574 num-tx-desc 512
575 }
576
577 dev 0000:02:00.1 {
578 num-rx-queues 2
579 name eth0
580 }
581 }
582
583dev <pci-dev> | default { .. }
584^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
585
586White-list [as in, attempt to drive] a specific PCI device. PCI-dev is a
587string of the form "DDDD:BB:SS.F" where:
588
589* DDDD = Domain
590* BB = Bus Number
591* SS = Slot number
592* F = Function
593
Paul Vinciguerra5ac392d2020-03-01 01:37:37 -0500594If the keyword **default** is used the values will apply to all the devices.
John DeNisco4f859682019-12-10 14:25:50 -0500595
596This is the same format used in the linux sysfs tree (i.e./sys/bus/pci/devices)
597for PCI device directory names.
598
599.. code-block:: console
600
601 dpdk {
602 dev default {
603 num-rx-desc 512
604 num-tx-desc 512
605 }
606
607dev <pci-dev> { .. }
608^^^^^^^^^^^^^^^^^^^^
609
610Whitelist specific interface by specifying PCI address. When whitelisting specific
611interfaces by specifying PCI address, additional custom parameters can also be
612specified. Valid options include:
613
614.. code-block:: console
615
616 dev 0000:02:00.0
617 dev 0000:03:00.0
618
619blacklist <pci-dev>
620^^^^^^^^^^^^^^^^^^^
621
622Blacklist specific device type by specifying PCI vendor:device Whitelist entries
623take precedence
624
625.. code-block:: console
626
627 blacklist 8086:10fb
628
629name interface-name
630^^^^^^^^^^^^^^^^^^^
631
632Set interface name
633
634.. code-block:: console
635
636 dev 0000:02:00.1 {
637 name eth0
638 }
639
640num-rx-queues <n>
641^^^^^^^^^^^^^^^^^
642
643Number of receive queues. Also enables RSS. Default value is 1.
644
645.. code-block:: console
646
647 dev 0000:02:00.1 {
Paul Vinciguerra5ac392d2020-03-01 01:37:37 -0500648 num-rx-queues <n>
John DeNisco4f859682019-12-10 14:25:50 -0500649 }
650
651num-tx-queues <n>
652^^^^^^^^^^^^^^^^^
653
654Number of transmit queues. Default is equal to number of worker threads
655or 1 if no workers treads.
656
657.. code-block:: console
658
659 dev 000:02:00.1 {
660 num-tx-queues <n>
661 }
662
663num-rx-desc <n>
664^^^^^^^^^^^^^^^
665
666Number of descriptors in receive ring. Increasing or reducing number
667can impact performance. Default is 1024.
668
669.. code-block:: console
670
671 dev 000:02:00.1 {
672 num-rx-desc <n>
673 }
674
John DeNisco4f859682019-12-10 14:25:50 -0500675uio-driver driver-name
676^^^^^^^^^^^^^^^^^^^^^^
677
678Change UIO driver used by VPP, Options are: igb_uio, vfio-pci, uio_pci_generic
679or auto (default)
680
681
682.. code-block:: console
683
684 uio-driver vfio-pci
685
Benoît Ganne6a073482022-10-13 17:22:26 +0200686uio-bind-force
687^^^^^^^^^^^^^^^^^^^^^^
688
689Force VPP to rebind the interface(s) to the selected UIO driver, even if the
690interface is up in Linux.
691By default, VPP will refuse to bind an interface if it is up in Linux,
692in case it is in active use.
693
694.. code-block:: console
695
696 uio-bind-force
697
John DeNisco4f859682019-12-10 14:25:50 -0500698no-multi-seg
699^^^^^^^^^^^^
700
701Disable multi-segment buffers, improves performance but disables Jumbo MTU support
702
703.. code-block:: console
704
705 no-multi-seg
706
707socket-mem <n>
708^^^^^^^^^^^^^^
709
710Change hugepages allocation per-socket, needed only if there is need for
711larger number of mbufs. Default is 256M on each detected CPU socket
712
713.. code-block:: console
714
715 socket-mem 2048,2048
716
717no-tx-checksum-offload
718^^^^^^^^^^^^^^^^^^^^^^
719
720Disables UDP / TCP TX checksum offload. Typically needed for use faster
721vector PMDs (together with no-multi-seg)
722
723.. code-block:: console
724
725 no-tx-checksum-offload
726
727enable-tcp-udp-checksum
728^^^^^^^^^^^^^^^^^^^^^^^
729
730Enable UDP / TCP TX checksum offload This is the reversed option of
731'no-tx-checksum-offload'
732
733.. code-block:: console
734
735 enable-tcp-udp-checksum
736
737The plugins Section
738-------------------
739
740Configure VPP plugins.
741
742.. code-block:: console
743
744 plugins {
745 path /ws/vpp/build-root/install-vpp-native/vpp/lib/vpp_plugins
746 plugin dpdk_plugin.so enable
747 }
748
749path pathname
750^^^^^^^^^^^^^
751
752Adjust the plugin path depending on where the VPP plugins are.
753
754.. code-block:: console
755
756 path /ws/vpp/build-root/install-vpp-native/vpp/lib/vpp_plugins
757
758plugin plugin-name | default enable | disable
759^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
760
761Disable all plugins by default and then selectively enable specific plugins
762
763.. code-block:: console
764
765 plugin default disable
766 plugin dpdk_plugin.so enable
767 plugin acl_plugin.so enable
768
769Enable all plugins by default and then selectively disable specific plugins
770
771.. code-block:: console
772
773 plugin dpdk_plugin.so disable
774 plugin acl_plugin.so disable
775
776Th statseg Section
777^^^^^^^^^^^^^^^^^^
778
779.. code-block:: console
780
781 statseg {
782 per-node-counters on
783 }
784
785socket-name <filename>
786^^^^^^^^^^^^^^^^^^^^^^
787
788Name of the stats segment socket defaults to /run/vpp/stats.sock.
789
790.. code-block:: console
791
792 socket-name /run/vpp/stats.sock
793
794size <nnn>[KMG]
795^^^^^^^^^^^^^^^
796
797The size of the stats segment, defaults to 32mb
798
799.. code-block:: console
800
801 size 1024M
802
803per-node-counters on | off
804^^^^^^^^^^^^^^^^^^^^^^^^^^
805
806Defaults to none
807
808.. code-block:: console
809
810 per-node-counters on
811
812update-interval <f64-seconds>
813^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
814
815Sets the segment scrape / update interval
816
817.. code-block:: console
818
819 update-interval 300
820
821
822Some Advanced Parameters:
823-------------------------
824
825
826acl-plugin Section
827------------------
John DeNisco06dcd452018-07-26 12:45:10 -0400828
andrew9f0c0202018-08-14 09:35:42 -0400829These parameters change the configuration of the ACL (access control list) plugin,
830such as how the ACL bi-hash tables are initialized.
John DeNisco06dcd452018-07-26 12:45:10 -0400831
andrew9f0c0202018-08-14 09:35:42 -0400832They should only be set by those that are familiar with the interworkings of VPP
833and the ACL Plugin.
834
835The first three parameters, *connection hash buckets*, *connection hash memory*,
836and *connection count max*, set the **connection table per-interface parameters**
837for modifying how the two bounded-index extensible hash tables for
838IPv6 (40\*8 bit key and 8\*8 bit value pairs) and IPv4
839(16\*8 bit key and 8\*8 bit value pairs) **ACL plugin FA interface sessions**
840are initialized.
John DeNisco06dcd452018-07-26 12:45:10 -0400841
John DeNisco4f859682019-12-10 14:25:50 -0500842connection hash buckets <n>
843^^^^^^^^^^^^^^^^^^^^^^^^^^^
844
845Sets the number of hash buckets (rounded up to a power of 2) in each
846of the two bi-hash tables. Defaults to 64\*1024 (65536) hash buckets.
847
848.. code-block:: console
849
850 connection hash buckets 65536
851
852connection hash memory <n>
853^^^^^^^^^^^^^^^^^^^^^^^^^^
854
855Sets the allocated memory size (in bytes) for each of the two bi-hash tables.
856Defaults to 1073741824 bytes.
857
858.. code-block:: console
859
860 connection hash memory 1073741824
861
862connection count max <n>
863^^^^^^^^^^^^^^^^^^^^^^^^
864
865Sets the maximum number of pool elements when allocating each per-worker
866pool of sessions for both bi-hash tables. Defaults to 500000 elements in each pool.
867
868.. code-block:: console
869
870 connection count max 500000
871
872main heap size <n>G | <n>M | <n>K | <n>
873^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
874
875Sets the size of the main memory heap that holds all the ACL module related
876allocations (other than hash.) Default size is 0, but during
877ACL heap initialization is equal to
878*per_worker_size_with_slack * tm->n_vlib_mains + bihash_size + main_slack*.
879Note that these variables are partially based on the
880**connection table per-interface parameters** mentioned above.
881
882.. code-block:: console
883
884 main heap size 3G
John DeNisco06dcd452018-07-26 12:45:10 -0400885
andrew9f0c0202018-08-14 09:35:42 -0400886The next three parameters, *hash lookup heap size*, *hash lookup hash buckets*,
887and *hash lookup hash memory*, modify the initialization of the bi-hash lookup
888table used by the ACL plugin. This table is initialized when attempting to apply
889an ACL to the existing vector of ACLs looked up during packet processing
890(but it is found that the table does not exist / has not been initialized yet.)
John DeNisco4f859682019-12-10 14:25:50 -0500891
892hash lookup heap size <n>G | <n>M | <n> K | <n>
893^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
894
895Sets the size of the memory heap that holds all the miscellaneous allocations
896related to hash-based lookups. Default size is 67108864 bytes.
897
898.. code-block:: console
899
900 hash lookup heap size 70M
901
902hash lookup hash buckets <n>
903^^^^^^^^^^^^^^^^^^^^^^^^^^^^
904
905Sets the number of hash buckets (rounded up to a power of 2) in the bi-hash
906lookup table. Defaults to 65536 hash buckets.
907
908.. code-block:: console
909
910 hash lookup hash buckets 65536
911
912hash lookup hash memory <n>
913^^^^^^^^^^^^^^^^^^^^^^^^^^^
914
915Sets the allocated memory size (in bytes) for the bi-hash lookup table.
916Defaults to 67108864 bytes.
917
918.. code-block:: console
919
920 hash lookup hash memory 67108864
921
922use tuple merge <n>
923^^^^^^^^^^^^^^^^^^^
924
925Sets a boolean value indicating whether or not to use TupleMerge
926for hash ACL's. Defaults to 1 (true), meaning the default implementation
927of hashing ACL's does use TupleMerge.
928
929.. code-block:: console
930
931 use tuple merge 1
932
933tuple merge split threshold <n>
934^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
935
936Sets the maximum amount of rules (ACE's) that can collide in a bi-hash
937lookup table before the table is split into two new tables. Splitting ensures
938less rule collisions by hashing colliding rules based on their common tuple
939(usually their maximum common tuple.) Splitting occurs when the
940*length of the colliding rules vector* is greater than this threshold amount.
941Defaults to a maximum of 39 rule collisions per table.
942
943.. code-block:: console
944
945 tuple merge split threshold 30
946
947reclassify sessions <n>
948^^^^^^^^^^^^^^^^^^^^^^^
949
950Sets a boolean value indicating whether or not to take the epoch of the session
951into account when dealing with re-applying ACL's or changing already applied ACL's.
952Defaults to 0 (false), meaning the default implementation does NOT take the
953epoch of the session into account.
954
955.. code-block:: console
956
957 reclassify sessions 1
John DeNisco06dcd452018-07-26 12:45:10 -0400958
959.. _api-queue:
960
John DeNisco4f859682019-12-10 14:25:50 -0500961api-queue Section
962-----------------
John DeNisco06dcd452018-07-26 12:45:10 -0400963
John DeNisco4f859682019-12-10 14:25:50 -0500964length <n>
965^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -0400966
John DeNisco4f859682019-12-10 14:25:50 -0500967Sets the api queue length. Minimum valid queue length is 1024, which is
968also the default.
John DeNisco06dcd452018-07-26 12:45:10 -0400969
John DeNisco4f859682019-12-10 14:25:50 -0500970.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -0400971
John DeNisco4f859682019-12-10 14:25:50 -0500972 length 2048
John DeNisco06dcd452018-07-26 12:45:10 -0400973
974.. _cj:
975
John DeNisco4f859682019-12-10 14:25:50 -0500976cj Section
977----------
John DeNisco06dcd452018-07-26 12:45:10 -0400978
979The circular journal (CJ) thread-safe circular log buffer scheme is
980occasionally useful when chasing bugs. Calls to it should not be checked in.
981See .../vlib/vlib/unix/cj.c. The circular journal is disables by default.
982When enabled, the number of records must be provided, there is no default
983value.
984
John DeNisco4f859682019-12-10 14:25:50 -0500985records <n>
986^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -0400987
John DeNisco4f859682019-12-10 14:25:50 -0500988Configure the number of circular journal records in the circular buffer.
989The number of records should be a power of 2.
John DeNisco06dcd452018-07-26 12:45:10 -0400990
John DeNisco4f859682019-12-10 14:25:50 -0500991.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -0400992
John DeNisco4f859682019-12-10 14:25:50 -0500993 records 131072
John DeNisco06dcd452018-07-26 12:45:10 -0400994
John DeNisco4f859682019-12-10 14:25:50 -0500995on
996^^
John DeNisco06dcd452018-07-26 12:45:10 -0400997
John DeNisco4f859682019-12-10 14:25:50 -0500998Turns on logging at the earliest possible moment.
John DeNisco06dcd452018-07-26 12:45:10 -0400999
John DeNisco4f859682019-12-10 14:25:50 -05001000.. code-block:: console
1001
1002 on
1003
1004dns Section
1005-----------
1006
1007max-cache-size <n>
1008^^^^^^^^^^^^^^^^^^
1009
1010Set the maximum number of active elements allowed in the pool of
1011dns cache entries. When resolving an expired entry or adding a new
1012static entry and the max number of active entries is reached,
1013a random, non-static entry is deleted. Defaults to 65535 entries.
1014
1015.. code-block:: console
1016
1017 max-cache-size 65535
1018
Paul Vinciguerra491741a2020-03-02 16:10:54 -05001019
1020ethernet Section
1021-----------------
1022
1023default-mtu <n>
1024^^^^^^^^^^^^^^^
1025
1026Specifies the default MTU size for Ethernet interfaces. Must be in
1027the range of 64-9000. The default is 9000.
1028
1029.. code-block:: console
1030
1031 default-mtu 1500
1032
John DeNisco4f859682019-12-10 14:25:50 -05001033heapsize Section
1034-----------------
John DeNisco06dcd452018-07-26 12:45:10 -04001035
1036Heapsize configuration controls the size of the main heap. The heap size is
1037configured very early in the boot sequence, before loading plug-ins or doing
1038much of anything else.
1039
John DeNisco4f859682019-12-10 14:25:50 -05001040heapsize <n>M | <n>G
1041^^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001042
Dave Barach2fef3df2020-02-21 17:31:17 -05001043Specifies the size of the heap in MB or GB. The default is 1GB.
John DeNisco06dcd452018-07-26 12:45:10 -04001044
John DeNisco4f859682019-12-10 14:25:50 -05001045.. code-block:: console
1046
1047 heapsize 2G
1048
1049ip Section
1050----------
John DeNisco06dcd452018-07-26 12:45:10 -04001051
1052IPv4 heap configuration. he heap size is configured very early in the boot
1053sequence, before loading plug-ins or doing much of anything else.
1054
John DeNisco4f859682019-12-10 14:25:50 -05001055heap-size <n>G | <n>M | <n>K | <n>
1056^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001057
John DeNisco4f859682019-12-10 14:25:50 -05001058Set the IPv4 mtrie heap size, which is the amount of memory dedicated to
1059the destination IP lookup table. The input value can be set in GB, MB, KB
1060or bytes. The default value is 32MB.
John DeNisco06dcd452018-07-26 12:45:10 -04001061
John DeNisco4f859682019-12-10 14:25:50 -05001062.. code-block:: console
1063
1064 heap-size 64M
1065
1066ip6 Section
1067-----------
John DeNisco06dcd452018-07-26 12:45:10 -04001068
1069IPv6 heap configuration. he heap size is configured very early in the boot
1070sequence, before loading plug-ins or doing much of anything else.
1071
1072
John DeNisco4f859682019-12-10 14:25:50 -05001073heap-size <n>G | <n>M | <n>K | <n>
1074^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001075
John DeNisco4f859682019-12-10 14:25:50 -05001076Set the IPv6 forwarding table heap size. The input value can be set in GB,
1077MB, KB or bytes. The default value is 32MB.
John DeNisco06dcd452018-07-26 12:45:10 -04001078
John DeNisco4f859682019-12-10 14:25:50 -05001079.. code-block:: console
1080
1081 heap-size 64M
1082
1083hash-buckets <n>
1084^^^^^^^^^^^^^^^^
1085
1086Set the number of IPv6 forwarding table hash buckets. The default value is
108764K (65536).
1088
1089.. code-block:: console
1090
1091 hash-buckets 131072
1092
1093l2learn Section
1094---------------
John DeNisco06dcd452018-07-26 12:45:10 -04001095
1096Configure Layer 2 MAC Address learning parameters.
1097
John DeNisco4f859682019-12-10 14:25:50 -05001098limit <n>
1099^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001100
John DeNisco4f859682019-12-10 14:25:50 -05001101Configures the number of L2 (MAC) addresses in the L2 FIB at any one time,
1102which limits the size of the L2 FIB to <n> concurrent entries. Defaults to
11034M entries (4194304).
John DeNisco06dcd452018-07-26 12:45:10 -04001104
John DeNisco4f859682019-12-10 14:25:50 -05001105.. code-block:: console
1106
1107 limit 8388608
1108
1109l2tp Section
1110------------
John DeNisco06dcd452018-07-26 12:45:10 -04001111
1112IPv6 Layer 2 Tunnelling Protocol Version 3 (IPv6-L2TPv3) configuration controls
1113the method used to locate a specific IPv6-L2TPv3 tunnel. The following settings
1114are mutually exclusive:
1115
John DeNisco4f859682019-12-10 14:25:50 -05001116lookup-v6-src
1117^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001118
John DeNisco4f859682019-12-10 14:25:50 -05001119Lookup tunnel by IPv6 source address.
John DeNisco06dcd452018-07-26 12:45:10 -04001120
John DeNisco4f859682019-12-10 14:25:50 -05001121.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -04001122
John DeNisco4f859682019-12-10 14:25:50 -05001123 lookup-v6-src
John DeNisco06dcd452018-07-26 12:45:10 -04001124
John DeNisco4f859682019-12-10 14:25:50 -05001125lookup-v6-dst
1126^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001127
John DeNisco4f859682019-12-10 14:25:50 -05001128Lookup tunnel by IPv6 destination address.
John DeNisco06dcd452018-07-26 12:45:10 -04001129
John DeNisco4f859682019-12-10 14:25:50 -05001130.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -04001131
John DeNisco4f859682019-12-10 14:25:50 -05001132 lookup-v6-dst
1133
1134lookup-session-id
1135^^^^^^^^^^^^^^^^^
1136
1137Lookup tunnel by L2TPv3 session identifier.
1138
1139.. code-block:: console
1140
1141 lookup-session-id
1142
1143logging Section
1144---------------
1145
1146size <n>
1147^^^^^^^^
1148
1149Number of entries in the global logging buffer. Defaults to 512.
1150
1151.. code-block:: console
1152
1153 size 512
1154
1155nthrottle-time <n>
1156^^^^^^^^^^^^^^^^^^
1157
1158Set the global value for the time to wait (in seconds) before resuming
1159logging of a log subclass that exceeded the per-subclass message-per-second
1160threshold. Defaults to 3.
1161
1162.. code-block:: console
1163
1164 unthrottle-time 3
1165
1166default-log-level emerg|alert | crit | err | warn | notice | info | debug | disabled
1167^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1168
1169Set the default logging level of the system log. Defaults to notice.
1170
1171.. code-block:: console
1172
1173 default-log-level notice
1174
1175default-syslog-log-level emerg|alert | crit | err | warn | notice | info | debug | disabled
1176^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1177
1178Set the default logging level of the syslog target. Defaults to warning.
1179
1180.. code-block:: console
1181
1182 default-syslog-log-level warning
1183
1184mactime Section
1185---------------
1186
1187lookup-table-buckets <n>
1188^^^^^^^^^^^^^^^^^^^^^^^^
1189
1190Sets the number of hash buckets in the mactime bi-hash lookup table.
1191Defaults to 128 buckets.
1192
1193.. code-block:: console
1194
1195 lookup-table-buckets 128
1196
1197lookup-table-memory <n>G | <n>M | <n>K | <n>
1198^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1199
1200Sets the allocated memory size (in bytes) for the mactime bi-hash lookup table.
1201The input value can be set in GB, MB, KB or bytes. The default value is 262144
1202(256 << 10) bytes or roughly 256KB.
1203
1204.. code-block:: console
1205
1206 lookup-table-memory 300K
1207
1208timezone_offset <n>
1209^^^^^^^^^^^^^^^^^^^
1210
1211Sets the timezone offset from UTC. Defaults to an offset of -5 hours
1212from UTC (US EST / EDT.)
1213
1214.. code-block:: console
1215
1216 timezone_offset -5
John DeNisco06dcd452018-07-26 12:45:10 -04001217
1218"map" Parameters
John DeNisco4f859682019-12-10 14:25:50 -05001219----------------
John DeNisco06dcd452018-07-26 12:45:10 -04001220
John DeNisco4f859682019-12-10 14:25:50 -05001221customer edge
1222^^^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001223
John DeNisco4f859682019-12-10 14:25:50 -05001224Sets a boolean true to indicate that the MAP node is a Customer Edge (CE)
1225router. The boolean defaults to false, meaning the MAP node is not treated
1226as a CE router.
John DeNisco06dcd452018-07-26 12:45:10 -04001227
John DeNisco4f859682019-12-10 14:25:50 -05001228.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -04001229
John DeNisco4f859682019-12-10 14:25:50 -05001230 customer edge
John DeNisco06dcd452018-07-26 12:45:10 -04001231
John DeNisco4f859682019-12-10 14:25:50 -05001232nat Section
1233-----------
John DeNisco06dcd452018-07-26 12:45:10 -04001234
andrew9f0c0202018-08-14 09:35:42 -04001235These parameters change the configuration of the NAT (Network address translation)
1236plugin, such as how the NAT & NAT64 bi-hash tables are initialized, if the NAT is
1237endpoint dependent, or if the NAT is deterministic.
1238
1239For each NAT per thread data, the following 4 parameters change how certain
1240bi-hash tables are initialized.
1241
John DeNisco4f859682019-12-10 14:25:50 -05001242translation hash buckets <n>
1243^^^^^^^^^^^^^^^^^^^^^^^^^^^^
andrew9f0c0202018-08-14 09:35:42 -04001244
John DeNisco4f859682019-12-10 14:25:50 -05001245Sets the number of hash buckets in each of the two in/out NAT bi-hash lookup
1246tables. Defaults to 1024 buckets.
andrew9f0c0202018-08-14 09:35:42 -04001247
John DeNisco4f859682019-12-10 14:25:50 -05001248If the NAT is indicated to be endpoint dependent, which can be set with the
1249:ref:`endpoint-dependent parameter <endpointLabel>`, then this parameter sets
1250the number of hash buckets in each of the two endpoint dependent sessions
1251NAT bi-hash lookup tables.
1252
1253.. code-block:: console
1254
1255 translation hash buckets 1024
1256
1257translation hash memory <n>
1258^^^^^^^^^^^^^^^^^^^^^^^^^^^
1259
1260Sets the allocated memory size (in bytes) for each of the two in/out NAT
1261bi-hash tables. Defaults to 134217728 (128 << 20) bytes, which is roughly 128 MB.
1262
1263If the NAT is indicated to be endpoint dependent, which can be set with the
1264:ref:`endpoint-dependent parameter <endpointLabel>`, then this parameter sets the
1265allocated memory size for each of the two endpoint dependent sessions NAT bi-hash
1266lookup tables.
1267
1268.. code-block:: console
1269
1270 translation hash memory 134217728
1271
1272user hash buckets <n>
1273^^^^^^^^^^^^^^^^^^^^^
1274
1275Sets the number of hash buckets in the user bi-hash lookup table
1276(src address lookup for a user.) Defaults to 128 buckets.
1277
1278.. code-block:: console
1279
1280 user hash buckets 128
1281
1282user hash memory <n>
1283^^^^^^^^^^^^^^^^^^^^
1284
1285Sets the allocated memory size (in bytes) for the user bi-hash lookup table
1286(src address lookup for a user.) Defaults to 67108864 (64 << 20) bytes,
1287which is roughly 64 MB.
1288
1289.. code-block:: console
1290
1291 user hash memory 67108864
1292
1293max translations per user <n>
1294^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1295
1296Sets the maximum amount of dynamic and/or static NAT sessions each user can have.
1297Defaults to 100. When this limit is reached, the least recently used translation
1298is recycled.
1299
1300.. code-block:: console
1301
1302 max translations per user 50
1303
1304deterministic
1305^^^^^^^^^^^^^
1306
1307Sets a boolean value to 1 indicating that the NAT is deterministic. Defaults to 0,
1308meaning the NAT is not deterministic.
1309
1310.. code-block:: console
1311
1312 deterministic
1313
1314nat64 bib hash buckets <n>
Jieqiang Wangaffa0552019-10-22 20:09:16 +08001315^^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco4f859682019-12-10 14:25:50 -05001316
1317Sets the number of hash buckets in each of the two in/out NAT64 BIB bi-hash
1318tables. Defaults to 1024 buckets.
1319
1320.. code-block:: console
1321
1322 nat64 bib hash buckets 1024
1323
1324nat64 bib hash memory <n>
Jieqiang Wangaffa0552019-10-22 20:09:16 +08001325^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco4f859682019-12-10 14:25:50 -05001326
1327Sets the allocated memory size (in bytes) for each of the two in/out NAT64
1328BIB bi-hash tables. Defaults to 134217728 (128 << 20) bytes,
1329which is roughly 128 MB.
1330
1331.. code-block:: console
1332
1333 nat64 bib hash memory 134217728
1334
1335nat64 st hash buckets <n>
Jieqiang Wangaffa0552019-10-22 20:09:16 +08001336^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco4f859682019-12-10 14:25:50 -05001337
1338Sets the number of hash buckets in each of the two in/out NAT64 session table
1339bi-hash tables. Defaults to 2048 buckets.
1340
1341.. code-block:: console
1342
1343 nat64 st hash buckets 2048
1344
1345nat64 st hash memory <n>
Jieqiang Wangaffa0552019-10-22 20:09:16 +08001346^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco4f859682019-12-10 14:25:50 -05001347
1348Sets the allocated memory size (in bytes) for each of the two in/out NAT64 session
1349table bi-hash tables. Defaults to 268435456 (256 << 20) bytes, which is roughly
1350256 MB.
1351
1352.. code-block:: console
1353
1354 nat64 st hash memory 268435456
1355
andrew9f0c0202018-08-14 09:35:42 -04001356.. _endpointLabel:
1357
John DeNisco4f859682019-12-10 14:25:50 -05001358endpoint-dependent
1359^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001360
John DeNisco4f859682019-12-10 14:25:50 -05001361Sets a boolean value to 1, indicating that the NAT is endpoint dependent.
1362Defaults to 0, meaning the NAT is not endpoint dependent.
John DeNisco06dcd452018-07-26 12:45:10 -04001363
John DeNisco4f859682019-12-10 14:25:50 -05001364.. code-block:: console
1365
1366 endpoint-dependent
1367
1368oam Section
1369-----------
John DeNisco06dcd452018-07-26 12:45:10 -04001370
1371OAM configuration controls the (ip4-icmp) interval, and number of misses
1372allowed before reporting an oam target down to any registered listener.
1373
John DeNisco4f859682019-12-10 14:25:50 -05001374interval <n.n>
1375^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001376
John DeNisco4f859682019-12-10 14:25:50 -05001377Interval, floating-point seconds, between sending OAM IPv4 ICMP messages.
1378Default is 2.04 seconds.
John DeNisco06dcd452018-07-26 12:45:10 -04001379
John DeNisco4f859682019-12-10 14:25:50 -05001380.. code-block:: console
andrew9f0c0202018-08-14 09:35:42 -04001381
John DeNisco4f859682019-12-10 14:25:50 -05001382 interval 3.5
John DeNisco06dcd452018-07-26 12:45:10 -04001383
Jieqiang Wangaffa0552019-10-22 20:09:16 +08001384physmem Section
1385---------------
1386
1387Configuration parameters used to specify base address and maximum size of
1388the memory allocated for the pmalloc module in VPP. pmalloc is a NUMA-aware,
1389growable physical memory allocator. pmalloc allocates memory for the DPDK
1390memory pool.
1391
1392base-addr <address>
1393^^^^^^^^^^^^^^^^^^^
1394
1395Specify the base address for pmalloc memory space.
1396
1397.. code-block:: console
1398
1399 base-addr 0xfffe00000000
1400
1401max-size <n>G | <n>M | <n>K | <n>
1402^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1403
1404Set the memory size for pmalloc memory space. The default is 16G.
1405
1406.. code-block:: console
1407
1408 max-size 4G
1409
John DeNisco4f859682019-12-10 14:25:50 -05001410tapcli Section
1411--------------
John DeNisco06dcd452018-07-26 12:45:10 -04001412
andrew9f0c0202018-08-14 09:35:42 -04001413Configuration parameters for TAPCLI (dynamic tap interface hookup.)
1414
John DeNisco4f859682019-12-10 14:25:50 -05001415mtu <n>
1416^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001417
John DeNisco4f859682019-12-10 14:25:50 -05001418Sets interface MTU (maximum transmission unit) size in bytes. This size
1419is also related to the number of MTU buffers. Defaults to 1500 bytes.
John DeNisco06dcd452018-07-26 12:45:10 -04001420
John DeNisco4f859682019-12-10 14:25:50 -05001421.. code-block:: console
1422
1423 mtu 1500
1424
1425disable
1426^^^^^^^
1427
1428Disables TAPCLI. Default is that TAPCLI is enabled.
1429
1430.. code-block:: console
1431
1432 disable
1433
1434
1435tcp Section
1436-----------
John DeNisco06dcd452018-07-26 12:45:10 -04001437
andrew9f0c0202018-08-14 09:35:42 -04001438Configuration parameters for TCP host stack utilities. The following
1439preallocation parameters are related to the initialization of fixed-size,
1440preallocation pools.
1441
John DeNisco4f859682019-12-10 14:25:50 -05001442preallocated-connections <n>
1443^^^^^^^^^^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001444
John DeNisco4f859682019-12-10 14:25:50 -05001445Sets the number of preallocated TCP connections. Defaults to 0.
1446The preallocated connections per thread is related to this value,
1447equal to (preallocated_connections / (num_threads - 1)).
John DeNisco06dcd452018-07-26 12:45:10 -04001448
John DeNisco4f859682019-12-10 14:25:50 -05001449.. code-block:: console
1450
1451 preallocated-connections 5
1452
1453preallocated-half-open-connections <n>
1454^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1455
1456Sets the number of preallocated TCP half-open connections. Defaults to 0.
1457
1458.. code-block:: console
1459
1460 preallocated-half-open-connections 5
1461
1462buffer-fail-fraction <n.n>
1463^^^^^^^^^^^^^^^^^^^^^^^^^^
1464
1465Sets the TCP buffer fail fraction (a float) used for fault-injection
1466when debugging TCP buffer allocation. Its use is found in *tcp_debug.h*.
1467Defaults to 0.0.
1468
1469.. code-block:: console
1470
1471 buffer-fail-fraction 0.0
1472
1473
1474tls Section
1475-----------
John DeNisco06dcd452018-07-26 12:45:10 -04001476
andrew9f0c0202018-08-14 09:35:42 -04001477Configures TLS parameters, such as enabling the use of test certificates.
1478These parameters affect the tlsmbedtls and tlsopenssl plugins.
1479
John DeNisco4f859682019-12-10 14:25:50 -05001480use-test-cert-in-ca
1481^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001482
John DeNisco4f859682019-12-10 14:25:50 -05001483Sets a boolean value to 1 to indicate during the initialization of a
1484TLS CA chain to attempt to parse and add test certificates to the chain.
1485Defaults to 0, meaning test certificates are not used.
John DeNisco06dcd452018-07-26 12:45:10 -04001486
John DeNisco4f859682019-12-10 14:25:50 -05001487.. code-block:: console
1488
1489 use-test-cert-in-ca
1490
1491ca-cert-path <filename>
1492^^^^^^^^^^^^^^^^^^^^^^^
1493
1494Sets the filename path of the location of TLS CA certificates, used when
1495initializing and loading TLS CA certificates during the initialization
1496of a TLS CA chain. If not set, the default filename path is
1497*/etc/ssl/certs/ca-certificates.crt*.
1498
1499.. code-block:: console
1500
1501 ca-cert-path /etc/ssl/certs/ca-certificates.crt
1502
1503
1504tuntap Section
1505--------------
John DeNisco06dcd452018-07-26 12:45:10 -04001506
1507The "tuntap" driver configures a point-to-point interface between the vpp
1508engine and the local Linux kernel stack. This allows e.g. users to ssh to the
1509host | VM | container via vpp "revenue" interfaces. It's marginally useful, and
1510is currently disabled by default. To [dynamically] create TAP interfaces - the
1511preferred scheme - see the "tap_connect" binary API. The Linux network stack
1512"vnet" interface needs to manually configure, and VLAN and other settings if
1513desired.
1514
John DeNisco06dcd452018-07-26 12:45:10 -04001515
John DeNisco4f859682019-12-10 14:25:50 -05001516enable|disable
1517^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001518
John DeNisco4f859682019-12-10 14:25:50 -05001519Enable or disable the tun/tap driver.
John DeNisco06dcd452018-07-26 12:45:10 -04001520
John DeNisco4f859682019-12-10 14:25:50 -05001521.. code-block:: console
John DeNisco06dcd452018-07-26 12:45:10 -04001522
John DeNisco4f859682019-12-10 14:25:50 -05001523 enable
1524
1525ethernet|ether
1526^^^^^^^^^^^^^^
1527
1528Create a tap device (ethernet MAC) instead of a tun device (point-to-point
1529tunnel). The two keywords are aliases for the same function.
1530
1531.. code-block:: console
1532
1533 ethernet
1534
1535have-normal-interface|have-normal
1536^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1537
1538Treat the host Linux stack as a routing peer instead of programming VPP
1539interface L3 addresses onto the tun/tap devices. The two keywords are
1540aliases for the same function.
1541
1542.. code-block:: console
1543
1544 have-normal-interface
1545
1546name <name>
1547^^^^^^^^^^^
1548
1549Assign name to the tun/tap device.
1550
1551.. code-block:: console
1552
1553 name vpp1
1554
1555
1556vhost-user Section
1557------------------
John DeNisco06dcd452018-07-26 12:45:10 -04001558
1559Vhost-user configuration parameters control the vhost-user driver.
1560
John DeNisco4f859682019-12-10 14:25:50 -05001561coalesce-frames <n>
1562^^^^^^^^^^^^^^^^^^^
John DeNisco06dcd452018-07-26 12:45:10 -04001563
John DeNisco4f859682019-12-10 14:25:50 -05001564Subject to deadline-timer expiration - see next item - attempt to transmit
1565at least <n> packet frames. Default is 32 frames.
John DeNisco06dcd452018-07-26 12:45:10 -04001566
John DeNisco4f859682019-12-10 14:25:50 -05001567.. code-block:: console
1568
1569 coalesce-frames 64
1570
1571coalesce-time <seconds>
1572^^^^^^^^^^^^^^^^^^^^^^^
1573
1574Hold packets no longer than (floating-point) seconds before transmitting
1575them. Default is 0.001 seconds
1576
1577.. code-block:: console
1578
1579 coalesce-time 0.002
1580
1581dont-dump-memory
1582^^^^^^^^^^^^^^^^
1583
1584vhost-user shared-memory segments can add up to a large amount of memory, so
1585it's handy to avoid adding them to corefiles when using a significant number
1586of such interfaces.
1587
1588.. code-block:: console
1589
1590 dont-dump-memory
1591
1592
1593vlib Section
1594------------
John DeNisco06dcd452018-07-26 12:45:10 -04001595
andrew9f0c0202018-08-14 09:35:42 -04001596These parameters configure VLIB, such as allowing you to choose whether to
1597enable memory traceback or a post-mortem elog dump.
1598
John DeNisco4f859682019-12-10 14:25:50 -05001599memory-trace
1600^^^^^^^^^^^^
1601
1602Enables memory trace (mheap traceback.) Defaults to 0, meaning memory
1603trace is disabled.
1604
1605.. code-block:: console
1606
1607 memory-trace
1608
1609elog-events <n>
1610^^^^^^^^^^^^^^^
1611
1612Sets the number of elements/events (the size) of the event ring
1613(a circular buffer of events.) This number rounds to a power of 2.
1614Defaults to 131072 (128 << 10) elements.
1615
1616.. code-block:: console
1617
1618 elog-events 4096
1619
1620elog-post-mortem-dump
1621^^^^^^^^^^^^^^^^^^^^^
1622
1623Enables the attempt of a post-mortem elog dump to
1624*/tmp/elog_post_mortem.<PID_OF_CALLING_PROCESS>* if os_panic or
1625os_exit is called.
1626
1627.. code-block:: console
1628
1629 elog-post-mortem-dump