startup.rst revision affa0553
1.. _startup:
2
3==========================================
4VPP Configuration - CLI and 'startup.conf'
5==========================================
6
7After a successful installation, VPP installs a startup config file named
8*startup.conf* in the */etc/vpp/* directory. This file can be tailored to
9make VPP run as desired, but contains default values for typical installations.
10
11Below are more details about this file and some of the the parameters and values
12it contains.
13
14Command-line Arguments
15----------------------
16
17Before 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
21Parameters 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
46
47Startup 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:**
61
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    }
71
72    api-trace {
73      on
74    }
75
76    dpdk {
77      dev 0000:03:00.0
78    }
79
80VPP is instructed to load this file with the -c option. For example:
81
82.. code-block:: console
83
84    $ sudo /usr/bin/vpp -c /etc/vpp/startup.conf
85
86Configuration Parameters
87------------------------
88
89Below 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**.
94
95For example, the invocation *'VLIB_CONFIG_FUNCTION (foo_config, "foo")'* will
96cause the function *'foo_config'* to receive all parameters given in a
97parameter block named "foo": "foo { arg1 arg2 arg3 ... }".
98
99The unix section
100----------------
101
102Configures VPP startup and behavior type attributes, as well and any OS based
103attributes.
104
105.. code-block:: console
106
107  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
126interactive
127^^^^^^^^^^^
128
129Attach CLI to stdin/out and provide a debugging command line interface.
130
131.. code-block:: console
132
133   interactive
134
135log <filename>
136^^^^^^^^^^^^^^
137
138Logs the startup configuration and all subsequent CLI commands in filename.
139Very useful in situations where folks don't remember or can't be bothered
140to include CLI commands in bug reports. The default *'startup.conf'* file
141is to write to *'/var/log/vpp/vpp.log'*.
142
143In VPP 18.04, the default log file location was moved from '/tmp/vpp.log'
144to '/var/log/vpp/vpp.log' . The VPP code is indifferent to the file location.
145However, if SELinux is enabled, then the new location is required for the file
146to be properly labeled. Check your local *'startup.conf'* file for the log file
147location on your system.
148
149.. code-block:: console
150
151   log /var/log/vpp/vpp-debug.log
152
153exec | startup-config <filename>
154^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
155
156Read startup operational configuration from filename. The contents of the file
157will be performed as though entered at the CLI. The two keywords are aliases
158for the same function; if both are specified, only the last will have an effect.
159
160A file of CLI commands might look like:
161
162.. code-block:: console
163
164   $ cat /usr/share/vpp/scripts/interface-up.txt
165   set interface state TenGigabitEthernet1/0/0 up
166   set interface state TenGigabitEthernet1/0/1 up
167
168Parameter Example:
169
170.. code-block:: console
171
172     startup-config /usr/share/vpp/scripts/interface-up.txt
173
174gid <number | name>
175^^^^^^^^^^^^^^^^^^^
176
177Sets the effective group ID to the input group ID or group name of the calling
178process.
179
180.. code-block:: console
181
182   gid vpp
183
184full-coredump
185^^^^^^^^^^^^^
186
187Ask the Linux kernel to dump all memory-mapped address regions, instead of
188just text+data+bss.
189
190.. code-block:: console
191
192   full-coredump
193
194coredump-size unlimited | <n>G | <n>M | <n>K | <n>
195^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
196
197     Set the maximum size of the coredump file. The input value can be set in
198     GB, MB, KB or bytes, or set to *'unlimited'*.
199
200.. code-block:: console
201
202   coredump-size unlimited
203
204cli-listen <ipaddress:port> | <socket-path>
205^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
206
207     Bind the CLI to listen at address localhost on TCP port 5002. This will
208     accept an ipaddress:port pair or a filesystem path; in the latter case a
209     local Unix socket is opened instead. The default *'startup.conf'* file
210     is to open the socket *'/run/vpp/cli.sock'*.
211
212.. code-block:: console
213
214     cli-listen localhost:5002
215     cli-listen /run/vpp/cli.sock
216
217cli-line-mode
218^^^^^^^^^^^^^
219
220     Disable character-by-character I/O on stdin. Useful when combined with,
221     for example, emacs M-x gud-gdb.
222
223.. code-block:: console
224
225   cli-line-mode
226
227cli-prompt <string>
228^^^^^^^^^^^^^^^^^^^
229
230     Configure the CLI prompt to be string.
231
232.. code-block:: console
233
234     cli-prompt vpp-2
235
236cli-history-limit <n>
237^^^^^^^^^^^^^^^^^^^^^
238
239     Limit command history to <n> lines. A value of 0 disables command history.
240     Default value: 50
241
242.. code-block:: console
243
244     cli-history-limit 100
245
246cli-no-banner
247^^^^^^^^^^^^^
248
249     Disable the login banner on stdin and Telnet connections.
250
251.. code-block:: console
252
253     cli-no-banner
254
255cli-no-pager
256^^^^^^^^^^^^
257
258     Disable the output pager.
259
260.. code-block:: console
261
262     cli-no-pager
263
264cli-pager-buffer-limit <n>
265^^^^^^^^^^^^^^^^^^^^^^^^^^
266
267     Limit pager buffer to <n> lines of output. A value of 0 disables the
268     pager. Default value: 100000
269
270.. code-block:: console
271
272     cli-pager-buffer-limit 5000
273
274runtime-dir <dir>
275^^^^^^^^^^^^^^^^^
276
277     Set the runtime directory, which is the default location for certain
278     files, like socket files. Default is based on User ID used to start VPP.
279     Typically it is *'root'*, which defaults to *'/run/vpp/'*. Otherwise,
280     defaults to *'/run/user/<uid>/vpp/'*.
281
282.. code-block:: console
283
284     runtime-dir /tmp/vpp
285
286poll-sleep-usec <n>
287^^^^^^^^^^^^^^^^^^^
288
289     Add a fixed-sleep between main loop poll. Default is 0, which is not to
290     sleep.
291
292.. code-block:: console
293
294     poll-sleep-usec 100
295
296pidfile <filename>
297^^^^^^^^^^^^^^^^^^
298
299     Writes the pid of the main thread in the given filename.
300
301.. code-block:: console
302
303     pidfile /run/vpp/vpp1.pid
304
305
306The api-trace Section
307---------------------
308
309The ability to trace, dump, and replay control-plane API traces makes all the
310difference in the world when trying to understand what the control-plane has
311tried to ask the forwarding-plane to do.
312
313Typically, one simply enables the API message trace scheme:
314
315.. code-block:: console
316
317   api-trace {
318     api-trace on
319   }
320
321on | enable
322^^^^^^^^^^^
323
324     Enable API trace capture from the beginning of time, and arrange for a
325     post-mortem dump of the API trace if the application terminates abnormally.
326     By default, the (circular) trace buffer will be configured to capture
327     256K traces. The default *'startup.conf'* file has trace enabled by default,
328     and unless there is a very strong reason, it should remain enabled.
329
330.. code-block:: console
331
332    on
333
334nitems <n>
335^^^^^^^^^^
336
337     Configure the circular trace buffer to contain the last <n> entries. By
338     default, the trace buffer captures the last 256K API messages received.
339
340.. code-block:: console
341
342    nitems 524288
343
344save-api-table <filename>
345^^^^^^^^^^^^^^^^^^^^^^^^^
346
347     Dumps the API message table to /tmp/<filename>.
348
349.. code-block:: console
350
351    save-api-table apiTrace-07-04.txt
352
353
354The api-segment Section
355-----------------------
356
357These values control various aspects of the binary API interface to VPP.
358
359The default looks like the following:
360
361.. code-block:: console
362
363   api-segment {
364     gid vpp
365   }
366
367
368prefix <path>
369^^^^^^^^^^^^^
370
371     Sets the prefix prepended to the name used for shared memory (SHM)
372     segments. The default is empty, meaning shared memory segments are created
373     directly in the SHM directory *'/dev/shm'*. It is worth noting that on
374     many systems *'/dev/shm'* is a symbolic link to somewhere else in the file
375     system; Ubuntu links it to *'/run/shm'*.
376
377.. code-block:: console
378
379    prefix /run/shm
380
381uid <number | name>
382^^^^^^^^^^^^^^^^^^^
383
384     Sets the user ID or name that should be used to set the ownership of the
385     shared memory segments. Defaults to the same user that VPP is started
386     with, probably root.
387
388.. code-block:: console
389
390    uid root
391
392gid <number | name>
393^^^^^^^^^^^^^^^^^^^
394
395     Sets the group ID or name that should be used to set the ownership of the
396     shared memory segments. Defaults to the same group that VPP is started
397     with, probably root.
398
399.. code-block:: console
400
401    gid vpp
402
403**The following parameters should only be set by those that are familiar with the
404interworkings of VPP.**
405
406baseva <x>
407^^^^^^^^^^
408
409     Set the base address for SVM global region. If not set, on AArch64, the
410     code will try to determine the base address. All other default to
411     0x30000000.
412
413.. code-block:: console
414
415    baseva 0x20000000
416
417global-size <n>G | <n>M | <n>
418^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
419
420     Set the global memory size, memory shared across all router instances,
421     packet buffers, etc. If not set, defaults to 64M. The input value can be
422     set in GB, MB or bytes.
423
424.. code-block:: console
425
426    global-size 2G
427
428global-pvt-heap-size <n>M | size <n>
429^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
430
431     Set the size of the global VM private mheap. If not set, defaults to 128k.
432     The input value can be set in MB or bytes.
433
434.. code-block:: console
435
436    global-pvt-heap-size size 262144
437
438api-pvt-heap-size <n>M | size <n>
439^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
440
441     Set the size of the api private mheap. If not set, defaults to 128k.
442     The input value can be set in MB or bytes.
443
444.. code-block:: console
445
446    api-pvt-heap-size 1M
447
448api-size <n>M | <n>G | <n>
449^^^^^^^^^^^^^^^^^^^^^^^^^^
450
451     Set the size of the API region. If not set, defaults to 16M. The input
452     value can be set in GB, MB or bytes.
453
454.. code-block:: console
455
456    api-size 64M
457
458The socksvr Section
459-------------------
460
461Enables a Unix domain socket which processes binary API messages. See
462.../vlibmemory/socket_api.c.  If this parameter is not set, vpp
463won't process binary API messages over sockets.
464
465.. code-block:: console
466
467   socksvr {
468      # Explicitly name a socket file
469      socket-name /run/vpp/api.sock
470      or
471      # Use defaults as described below
472      default
473   }
474
475The "default" keyword instructs vpp to use /run/vpp/api.sock when
476running as root, otherwise to use /run/user/<uid>/api.sock.
477
478The cpu Section
479---------------
480
481In the VPP there is one main thread and optionally the user can create worker(s)
482The main thread and worker thread(s) can be pinned to CPU core(s) manually or automatically
483
484.. code-block:: console
485
486   cpu {
487      main-core 1
488      corelist-workers 2-3,18-19
489   }
490
491
492Manual pinning of thread(s) to CPU core(s)
493^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
494
495main-core
496^^^^^^^^^
497
498Set logical CPU core where main thread runs, if main core is not set VPP will use
499core 1 if available
500
501.. code-block:: console
502
503   main-core 1
504
505corelist-workers
506^^^^^^^^^^^^^^^^
507
508Set logical CPU core(s) where worker threads are running
509
510.. code-block:: console
511
512   corelist-workers 2-3,18-19
513
514Automatic pinning of thread(s) to CPU core(s)
515^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
516
517skip-cores number
518^^^^^^^^^^^^^^^^^
519
520Sets number of CPU core(s) to be skipped (1 ... N-1), Skipped CPU core(s) are
521not used for pinning main thread and working thread(s).
522
523The main thread is automatically pinned to the first available CPU core and worker(s)
524are pinned to next free CPU core(s) after core assigned to main thread
525
526.. code-block:: console
527
528   skip-cores 4
529
530workers number
531^^^^^^^^^^^^^^
532
533Specify a number of workers to be created Workers are pinned to N consecutive
534CPU cores while skipping "skip-cores" CPU core(s) and main thread's CPU core
535
536.. code-block:: console
537
538   workers 2
539
540scheduler-policy other | batch | idle | fifo | rr
541^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
542
543Set scheduling policy and priority of main and worker threads
544
545Scheduling policy options are: other (SCHED_OTHER), batch (SCHED_BATCH)
546idle (SCHED_IDLE), fifo (SCHED_FIFO), rr (SCHED_RR)
547
548.. code-block:: console
549
550   scheduler-policy fifo
551
552scheduler-priority number
553^^^^^^^^^^^^^^^^^^^^^^^^^
554
555Scheduling priority is used only for "real-time policies (fifo and rr),
556and has to be in the range of priorities supported for a particular policy
557
558.. code-block:: console
559
560   scheduler-priority 50
561
562The buffers Section
563-------------------
564
565.. code-block:: console
566
567   buffers {
568      buffers-per-numa 128000
569      default data-size 2048
570   }
571
572buffers-per-numa number
573^^^^^^^^^^^^^^^^^^^^^^^
574
575Increase number of buffers allocated, needed only in scenarios with
576large number of interfaces and worker threads. Value is per numa node.
577Default is 16384 (8192 if running unpriviledged)
578
579.. code-block:: console
580
581   buffers-per-numa 128000
582
583default data-size number
584^^^^^^^^^^^^^^^^^^^^^^^^
585
586Size of buffer data area, default is 2048
587
588.. code-block:: console
589
590   default data-size 2048
591
592
593The dpdk Section
594----------------
595
596.. code-block:: console
597
598   dpdk {
599      dev default {
600         num-rx-desc 512
601         num-tx-desc 512
602      }
603
604      dev 0000:02:00.1 {
605         num-rx-queues 2
606         name eth0
607      }
608   }
609
610dev <pci-dev> | default { .. }
611^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
612
613White-list [as in, attempt to drive] a specific PCI device. PCI-dev is a
614string of the form "DDDD:BB:SS.F" where:
615
616* DDDD = Domain
617* BB = Bus Number
618* SS = Slot number
619* F = Function
620
621If the keywork **default** is used the values will apply to all the devices.
622
623This is the same format used in the linux sysfs tree (i.e./sys/bus/pci/devices)
624for PCI device directory names.
625
626.. code-block:: console
627
628   dpdk {
629      dev default {
630         num-rx-desc 512
631         num-tx-desc 512
632      }
633
634dev <pci-dev> { .. }
635^^^^^^^^^^^^^^^^^^^^
636
637Whitelist specific interface by specifying PCI address. When whitelisting specific
638interfaces by specifying PCI address, additional custom parameters can also be
639specified. Valid options include:
640
641.. code-block:: console
642
643   dev 0000:02:00.0
644   dev 0000:03:00.0
645
646blacklist <pci-dev>
647^^^^^^^^^^^^^^^^^^^
648
649Blacklist specific device type by specifying PCI vendor:device Whitelist entries
650take precedence
651
652.. code-block:: console
653
654   blacklist 8086:10fb
655
656name interface-name
657^^^^^^^^^^^^^^^^^^^
658
659Set interface name
660
661.. code-block:: console
662
663   dev 0000:02:00.1 {
664      name eth0
665   }
666
667num-rx-queues <n>
668^^^^^^^^^^^^^^^^^
669
670Number of receive queues. Also enables RSS. Default value is 1.
671
672.. code-block:: console
673
674   dev 0000:02:00.1 {
675      num-tx-queues <n>
676   }
677
678num-tx-queues <n>
679^^^^^^^^^^^^^^^^^
680
681Number of transmit queues. Default is equal to number of worker threads
682or 1 if no workers treads.
683
684.. code-block:: console
685
686   dev 000:02:00.1 {
687      num-tx-queues <n>
688   }
689
690num-rx-desc <n>
691^^^^^^^^^^^^^^^
692
693Number of descriptors in receive ring. Increasing or reducing number
694can impact performance. Default is 1024.
695
696.. code-block:: console
697
698   dev 000:02:00.1 {
699      num-rx-desc <n>
700   }
701
702vlan-strip-offload on | off
703^^^^^^^^^^^^^^^^^^^^^^^^^^^
704
705VLAN strip offload mode for interface. VLAN stripping is off by default
706for all NICs except VICs, using ENIC driver, which has VLAN stripping on
707by default.
708
709.. code-block:: console
710
711   dev 000:02:00.1 {
712      vlan-strip-offload on|off
713   }
714
715uio-driver driver-name
716^^^^^^^^^^^^^^^^^^^^^^
717
718Change UIO driver used by VPP, Options are: igb_uio, vfio-pci, uio_pci_generic
719or auto (default)
720
721
722.. code-block:: console
723
724   uio-driver vfio-pci
725
726no-multi-seg
727^^^^^^^^^^^^
728
729Disable multi-segment buffers, improves performance but disables Jumbo MTU support
730
731.. code-block:: console
732
733   no-multi-seg
734
735socket-mem <n>
736^^^^^^^^^^^^^^
737
738Change hugepages allocation per-socket, needed only if there is need for
739larger number of mbufs. Default is 256M on each detected CPU socket
740
741.. code-block:: console
742
743   socket-mem 2048,2048
744
745no-tx-checksum-offload
746^^^^^^^^^^^^^^^^^^^^^^
747
748Disables UDP / TCP TX checksum offload. Typically needed for use faster
749vector PMDs (together with no-multi-seg)
750
751.. code-block:: console
752
753   no-tx-checksum-offload
754
755enable-tcp-udp-checksum
756^^^^^^^^^^^^^^^^^^^^^^^
757
758Enable UDP / TCP TX checksum offload This is the reversed option of
759'no-tx-checksum-offload'
760
761.. code-block:: console
762
763   enable-tcp-udp-checksum
764
765The plugins Section
766-------------------
767
768Configure VPP plugins.
769
770.. code-block:: console
771
772   plugins {
773      path /ws/vpp/build-root/install-vpp-native/vpp/lib/vpp_plugins
774      plugin dpdk_plugin.so enable
775   }
776
777path pathname
778^^^^^^^^^^^^^
779
780Adjust the plugin path depending on where the VPP plugins are.
781
782.. code-block:: console
783
784   path /ws/vpp/build-root/install-vpp-native/vpp/lib/vpp_plugins
785
786plugin plugin-name | default enable | disable
787^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
788
789Disable all plugins by default and then selectively enable specific plugins
790
791.. code-block:: console
792
793   plugin default disable
794   plugin dpdk_plugin.so enable
795   plugin acl_plugin.so enable
796
797Enable all plugins by default and then selectively disable specific plugins
798
799.. code-block:: console
800
801   plugin dpdk_plugin.so disable
802   plugin acl_plugin.so disable
803
804Th statseg Section
805^^^^^^^^^^^^^^^^^^
806
807.. code-block:: console
808
809   statseg {
810      per-node-counters on
811    }
812
813socket-name <filename>
814^^^^^^^^^^^^^^^^^^^^^^
815
816Name of the stats segment socket defaults to /run/vpp/stats.sock.
817
818.. code-block:: console
819
820   socket-name /run/vpp/stats.sock
821
822size <nnn>[KMG]
823^^^^^^^^^^^^^^^
824
825The size of the stats segment, defaults to 32mb
826
827.. code-block:: console
828
829   size 1024M
830
831per-node-counters on | off
832^^^^^^^^^^^^^^^^^^^^^^^^^^
833
834Defaults to none
835
836.. code-block:: console
837
838   per-node-counters on
839
840update-interval <f64-seconds>
841^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
842
843Sets the segment scrape / update interval
844
845.. code-block:: console
846
847   update-interval 300
848
849
850Some Advanced Parameters:
851-------------------------
852
853
854acl-plugin Section
855------------------
856
857These parameters change the configuration of the ACL (access control list) plugin,
858such as how the ACL bi-hash tables are initialized.
859
860They should only be set by those that are familiar with the interworkings of VPP
861and the ACL Plugin.
862
863The first three parameters, *connection hash buckets*, *connection hash memory*,
864and *connection count max*, set the **connection table per-interface parameters**
865for modifying how the two bounded-index extensible hash tables for
866IPv6 (40\*8 bit key and 8\*8 bit value pairs) and IPv4
867(16\*8 bit key and 8\*8 bit value pairs) **ACL plugin FA interface sessions**
868are initialized.
869
870connection hash buckets <n>
871^^^^^^^^^^^^^^^^^^^^^^^^^^^
872
873Sets the number of hash buckets (rounded up to a power of 2) in each
874of the two bi-hash tables. Defaults to 64\*1024 (65536) hash buckets.
875
876.. code-block:: console
877
878   connection hash buckets 65536
879
880connection hash memory <n>
881^^^^^^^^^^^^^^^^^^^^^^^^^^
882
883Sets the allocated memory size (in bytes) for each of the two bi-hash tables.
884Defaults to 1073741824 bytes.
885
886.. code-block:: console
887
888   connection hash memory 1073741824
889
890connection count max <n>
891^^^^^^^^^^^^^^^^^^^^^^^^
892
893Sets the maximum number of pool elements when allocating each per-worker
894pool of sessions for both bi-hash tables. Defaults to 500000 elements in each pool.
895
896.. code-block:: console
897
898   connection count max 500000
899
900main heap size <n>G | <n>M | <n>K | <n>
901^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
902
903Sets the size of the main memory heap that holds all the ACL module related
904allocations (other than hash.) Default size is 0, but during
905ACL heap initialization is equal to
906*per_worker_size_with_slack * tm->n_vlib_mains + bihash_size + main_slack*.
907Note that these variables are partially based on the
908**connection table per-interface parameters** mentioned above.
909
910.. code-block:: console
911
912   main heap size 3G
913
914The next three parameters, *hash lookup heap size*, *hash lookup hash buckets*,
915and *hash lookup hash memory*, modify the initialization of the bi-hash lookup
916table used by the ACL plugin. This table is initialized when attempting to apply
917an ACL to the existing vector of ACLs looked up during packet processing
918(but it is found that the table does not exist / has not been initialized yet.)
919
920hash lookup heap size  <n>G | <n>M | <n> K | <n>
921^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
922
923Sets the size of the memory heap that holds all the miscellaneous allocations
924related to hash-based lookups. Default size is 67108864 bytes.
925
926.. code-block:: console
927
928   hash lookup heap size 70M
929
930hash lookup hash buckets <n>
931^^^^^^^^^^^^^^^^^^^^^^^^^^^^
932
933Sets the number of hash buckets (rounded up to a power of 2) in the bi-hash
934lookup table. Defaults to 65536 hash buckets.
935
936.. code-block:: console
937
938   hash lookup hash buckets 65536
939
940hash lookup hash memory <n>
941^^^^^^^^^^^^^^^^^^^^^^^^^^^
942
943Sets the allocated memory size (in bytes) for the bi-hash lookup table.
944Defaults to 67108864 bytes.
945
946.. code-block:: console
947
948   hash lookup hash memory 67108864
949
950use tuple merge <n>
951^^^^^^^^^^^^^^^^^^^
952
953Sets a boolean value indicating whether or not to use TupleMerge
954for hash ACL's. Defaults to 1 (true), meaning the default implementation
955of hashing ACL's does use TupleMerge.
956
957.. code-block:: console
958
959   use tuple merge 1
960
961tuple merge split threshold <n>
962^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
963
964Sets the maximum amount of rules (ACE's) that can collide in a bi-hash
965lookup table before the table is split into two new tables. Splitting ensures
966less rule collisions by hashing colliding rules based on their common tuple
967(usually their maximum common tuple.) Splitting occurs when the
968*length of the colliding rules vector* is greater than this threshold amount.
969Defaults to a maximum of 39 rule collisions per table.
970
971.. code-block:: console
972
973   tuple merge split threshold 30
974
975reclassify sessions <n>
976^^^^^^^^^^^^^^^^^^^^^^^
977
978Sets a boolean value indicating whether or not to take the epoch of the session
979into account when dealing with re-applying ACL's or changing already applied ACL's.
980Defaults to 0 (false), meaning the default implementation does NOT take the
981epoch of the session into account.
982
983.. code-block:: console
984
985   reclassify sessions 1
986
987.. _api-queue:
988
989api-queue Section
990-----------------
991
992length  <n>
993^^^^^^^^^^^
994
995Sets the api queue length. Minimum valid queue length is 1024, which is
996also the default.
997
998.. code-block:: console
999
1000   length 2048
1001
1002.. _cj:
1003
1004cj Section
1005----------
1006
1007The circular journal (CJ) thread-safe circular log buffer scheme is
1008occasionally useful when chasing bugs. Calls to it should not be checked in.
1009See .../vlib/vlib/unix/cj.c. The circular journal is disables by default.
1010When enabled, the number of records must be provided, there is no default
1011value.
1012
1013records <n>
1014^^^^^^^^^^^
1015
1016Configure the number of circular journal records in the circular buffer.
1017The number of records should be a power of 2.
1018
1019.. code-block:: console
1020
1021   records 131072
1022
1023on
1024^^
1025
1026Turns on logging at the earliest possible moment.
1027
1028.. code-block:: console
1029
1030   on
1031
1032dns Section
1033-----------
1034
1035max-cache-size <n>
1036^^^^^^^^^^^^^^^^^^
1037
1038Set the maximum number of active elements allowed in the pool of
1039dns cache entries. When resolving an expired entry or adding a new
1040static entry and the max number of active entries is reached,
1041a random, non-static entry is deleted. Defaults to 65535 entries.
1042
1043.. code-block:: console
1044
1045   max-cache-size 65535
1046
1047heapsize Section
1048-----------------
1049
1050Heapsize configuration controls the size of the main heap. The heap size is
1051configured very early in the boot sequence, before loading plug-ins or doing
1052much of anything else.
1053
1054heapsize <n>M | <n>G
1055^^^^^^^^^^^^^^^^^^^^
1056
1057Specifies the size of the heap in MB or GB. The default is 1GB. Setting the
1058main heap size to 4GB or more requires recompilation of the entire system
1059with CLIB_VEC64 > 0. See .../clib/clib/vec_bootstrap.h.
1060
1061.. code-block:: console
1062
1063   heapsize 2G
1064
1065ip Section
1066----------
1067
1068IPv4 heap configuration. he heap size is configured very early in the boot
1069sequence, before loading plug-ins or doing much of anything else.
1070
1071heap-size <n>G | <n>M | <n>K | <n>
1072^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1073
1074Set the IPv4 mtrie heap size, which is the amount of memory dedicated to
1075the destination IP lookup table. The input value can be set in GB, MB, KB
1076or bytes. The default value is 32MB.
1077
1078.. code-block:: console
1079
1080   heap-size 64M
1081
1082ip6 Section
1083-----------
1084
1085IPv6 heap configuration. he heap size is configured very early in the boot
1086sequence, before loading plug-ins or doing much of anything else.
1087
1088
1089heap-size <n>G | <n>M | <n>K | <n>
1090^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1091
1092Set the IPv6 forwarding table heap size. The input value can be set in GB,
1093MB, KB or bytes. The default value is 32MB.
1094
1095.. code-block:: console
1096
1097   heap-size 64M
1098
1099hash-buckets <n>
1100^^^^^^^^^^^^^^^^
1101
1102Set the number of IPv6 forwarding table hash buckets. The default value is
110364K (65536).
1104
1105.. code-block:: console
1106
1107   hash-buckets 131072
1108
1109l2learn Section
1110---------------
1111
1112Configure Layer 2 MAC Address learning parameters.
1113
1114limit <n>
1115^^^^^^^^^
1116
1117Configures the number of L2 (MAC) addresses in the L2 FIB at any one time,
1118which limits the size of the L2 FIB to <n> concurrent entries.  Defaults to
11194M entries (4194304).
1120
1121.. code-block:: console
1122
1123   limit 8388608
1124
1125l2tp Section
1126------------
1127
1128IPv6 Layer 2 Tunnelling Protocol Version 3 (IPv6-L2TPv3) configuration controls
1129the method used to locate a specific IPv6-L2TPv3 tunnel. The following settings
1130are mutually exclusive:
1131
1132lookup-v6-src
1133^^^^^^^^^^^^^
1134
1135Lookup tunnel by IPv6 source address.
1136
1137.. code-block:: console
1138
1139   lookup-v6-src
1140
1141lookup-v6-dst
1142^^^^^^^^^^^^^
1143
1144Lookup tunnel by IPv6 destination address.
1145
1146.. code-block:: console
1147
1148   lookup-v6-dst
1149
1150lookup-session-id
1151^^^^^^^^^^^^^^^^^
1152
1153Lookup tunnel by L2TPv3 session identifier.
1154
1155.. code-block:: console
1156
1157   lookup-session-id
1158
1159logging Section
1160---------------
1161
1162size <n>
1163^^^^^^^^
1164
1165Number of entries in the global logging buffer. Defaults to 512.
1166
1167.. code-block:: console
1168
1169   size 512
1170
1171nthrottle-time <n>
1172^^^^^^^^^^^^^^^^^^
1173
1174Set the global value for the time to wait (in seconds) before resuming
1175logging of a log subclass that exceeded the per-subclass message-per-second
1176threshold.  Defaults to 3.
1177
1178.. code-block:: console
1179
1180   unthrottle-time 3
1181
1182default-log-level emerg|alert | crit | err | warn | notice | info | debug | disabled
1183^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1184
1185Set the default logging level of the system log.  Defaults to notice.
1186
1187.. code-block:: console
1188
1189   default-log-level notice
1190
1191default-syslog-log-level emerg|alert | crit | err | warn | notice | info | debug | disabled
1192^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1193
1194Set the default logging level of the syslog target.  Defaults to warning.
1195
1196.. code-block:: console
1197
1198   default-syslog-log-level warning
1199
1200mactime Section
1201---------------
1202
1203lookup-table-buckets <n>
1204^^^^^^^^^^^^^^^^^^^^^^^^
1205
1206Sets the number of hash buckets in the mactime bi-hash lookup table.
1207Defaults to 128 buckets.
1208
1209.. code-block:: console
1210
1211   lookup-table-buckets 128
1212
1213lookup-table-memory <n>G | <n>M | <n>K | <n>
1214^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1215
1216Sets the allocated memory size (in bytes) for the mactime bi-hash lookup table.
1217The input value can be set in GB, MB, KB or bytes. The default value is 262144
1218(256 << 10) bytes or roughly 256KB.
1219
1220.. code-block:: console
1221
1222   lookup-table-memory 300K
1223
1224timezone_offset <n>
1225^^^^^^^^^^^^^^^^^^^
1226
1227Sets the timezone offset from UTC. Defaults to an offset of -5 hours
1228from UTC (US EST / EDT.)
1229
1230.. code-block:: console
1231
1232   timezone_offset -5
1233
1234"map" Parameters
1235----------------
1236
1237customer edge
1238^^^^^^^^^^^^^^^^^^^^^^^^^^^
1239
1240Sets a boolean true to indicate that the MAP node is a Customer Edge (CE)
1241router. The boolean defaults to false, meaning the MAP node is not treated
1242as a CE router.
1243
1244.. code-block:: console
1245
1246   customer edge
1247
1248nat Section
1249-----------
1250
1251These parameters change the configuration of the NAT (Network address translation)
1252plugin, such as how the NAT & NAT64 bi-hash tables are initialized, if the NAT is
1253endpoint dependent, or if the NAT is deterministic.
1254
1255For each NAT per thread data, the following 4 parameters change how certain
1256bi-hash tables are initialized.
1257
1258translation hash buckets <n>
1259^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1260
1261Sets the number of hash buckets in each of the two in/out NAT bi-hash lookup
1262tables. Defaults to 1024 buckets.
1263
1264If the NAT is indicated to be endpoint dependent, which can be set with the
1265:ref:`endpoint-dependent parameter <endpointLabel>`, then this parameter sets
1266the number of hash buckets in each of the two endpoint dependent sessions
1267NAT bi-hash lookup tables.
1268
1269.. code-block:: console
1270
1271   translation hash buckets 1024
1272
1273translation hash memory <n>
1274^^^^^^^^^^^^^^^^^^^^^^^^^^^
1275
1276Sets the allocated memory size (in bytes) for each of the two in/out NAT
1277bi-hash tables. Defaults to 134217728 (128 << 20) bytes, which is roughly 128 MB.
1278
1279If the NAT is indicated to be endpoint dependent, which can be set with the
1280:ref:`endpoint-dependent parameter <endpointLabel>`, then this parameter sets the
1281allocated memory size for each of the two endpoint dependent sessions NAT bi-hash
1282lookup tables.
1283
1284.. code-block:: console
1285
1286   translation hash memory 134217728
1287
1288user hash buckets <n>
1289^^^^^^^^^^^^^^^^^^^^^
1290
1291Sets the number of hash buckets in the user bi-hash lookup table
1292(src address lookup for a user.) Defaults to 128 buckets.
1293
1294.. code-block:: console
1295
1296   user hash buckets 128
1297
1298user hash memory <n>
1299^^^^^^^^^^^^^^^^^^^^
1300
1301Sets the allocated memory size (in bytes) for the user bi-hash lookup table
1302(src address lookup for a user.) Defaults to 67108864 (64 << 20) bytes,
1303which is roughly 64 MB.
1304
1305.. code-block:: console
1306
1307   user hash memory 67108864
1308
1309max translations per user <n>
1310^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1311
1312Sets the maximum amount of dynamic and/or static NAT sessions each user can have.
1313Defaults to 100. When this limit is reached, the least recently used translation
1314is recycled.
1315
1316.. code-block:: console
1317
1318   max translations per user 50
1319
1320deterministic
1321^^^^^^^^^^^^^
1322
1323Sets a boolean value to 1 indicating that the NAT is deterministic. Defaults to 0,
1324meaning the NAT is not deterministic.
1325
1326.. code-block:: console
1327
1328   deterministic
1329
1330nat64 bib hash buckets <n>
1331^^^^^^^^^^^^^^^^^^^^^^^^^^
1332
1333Sets the number of hash buckets in each of the two in/out NAT64 BIB bi-hash
1334tables. Defaults to 1024 buckets.
1335
1336.. code-block:: console
1337
1338   nat64 bib hash buckets 1024
1339
1340nat64 bib hash memory <n>
1341^^^^^^^^^^^^^^^^^^^^^^^^^
1342
1343Sets the allocated memory size (in bytes) for each of the two in/out NAT64
1344BIB bi-hash tables. Defaults to 134217728 (128 << 20) bytes,
1345which is roughly 128 MB.
1346
1347.. code-block:: console
1348
1349   nat64 bib hash memory 134217728
1350
1351nat64 st hash buckets <n>
1352^^^^^^^^^^^^^^^^^^^^^^^^^
1353
1354Sets the number of hash buckets in each of the two in/out NAT64 session table
1355bi-hash tables. Defaults to 2048 buckets.
1356
1357.. code-block:: console
1358
1359   nat64 st hash buckets 2048
1360
1361nat64 st hash memory <n>
1362^^^^^^^^^^^^^^^^^^^^^^^^
1363
1364Sets the allocated memory size (in bytes) for each of the two in/out NAT64 session
1365table bi-hash tables. Defaults to 268435456 (256 << 20) bytes, which is roughly
1366256 MB.
1367
1368.. code-block:: console
1369
1370   nat64 st hash memory 268435456
1371
1372.. _endpointLabel:
1373
1374endpoint-dependent
1375^^^^^^^^^^^^^^^^^^
1376
1377Sets a boolean value to 1, indicating that the NAT is endpoint dependent.
1378Defaults to 0, meaning the NAT is not endpoint dependent.
1379
1380.. code-block:: console
1381
1382   endpoint-dependent
1383
1384oam Section
1385-----------
1386
1387OAM configuration controls the (ip4-icmp) interval, and number of misses
1388allowed before reporting an oam target down to any registered listener.
1389
1390interval <n.n>
1391^^^^^^^^^^^^^^
1392
1393Interval, floating-point seconds, between sending OAM IPv4 ICMP messages.
1394Default is 2.04 seconds.
1395
1396.. code-block:: console
1397
1398   interval 3.5
1399
1400physmem Section
1401---------------
1402
1403Configuration parameters used to specify base address and maximum size of
1404the memory allocated for the pmalloc module in VPP. pmalloc is a NUMA-aware,
1405growable physical memory allocator. pmalloc allocates memory for the DPDK
1406memory pool.
1407
1408base-addr <address>
1409^^^^^^^^^^^^^^^^^^^
1410
1411Specify the base address for pmalloc memory space.
1412
1413.. code-block:: console
1414
1415    base-addr 0xfffe00000000
1416
1417max-size <n>G | <n>M | <n>K | <n>
1418^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1419
1420Set the memory size for pmalloc memory space. The default is 16G.
1421
1422.. code-block:: console
1423
1424    max-size 4G
1425
1426tapcli Section
1427--------------
1428
1429Configuration parameters for TAPCLI (dynamic tap interface hookup.)
1430
1431mtu <n>
1432^^^^^^^
1433
1434Sets interface MTU (maximum transmission unit) size in bytes. This size
1435is also related to the number of MTU buffers. Defaults to 1500 bytes.
1436
1437.. code-block:: console
1438
1439   mtu 1500
1440
1441disable
1442^^^^^^^
1443
1444Disables TAPCLI. Default is that TAPCLI is enabled.
1445
1446.. code-block:: console
1447
1448   disable
1449
1450
1451tcp Section
1452-----------
1453
1454Configuration parameters for TCP host stack utilities. The following
1455preallocation parameters are related to the initialization of fixed-size,
1456preallocation pools.
1457
1458preallocated-connections <n>
1459^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1460
1461Sets the number of preallocated TCP connections. Defaults to 0.
1462The preallocated connections per thread is related to this value,
1463equal to (preallocated_connections / (num_threads - 1)).
1464
1465.. code-block:: console
1466
1467   preallocated-connections 5
1468
1469preallocated-half-open-connections <n>
1470^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1471
1472Sets the number of preallocated TCP half-open connections. Defaults to 0.
1473
1474.. code-block:: console
1475
1476   preallocated-half-open-connections 5
1477
1478buffer-fail-fraction <n.n>
1479^^^^^^^^^^^^^^^^^^^^^^^^^^
1480
1481Sets the TCP buffer fail fraction (a float) used for fault-injection
1482when debugging TCP buffer allocation. Its use is found in *tcp_debug.h*.
1483Defaults to 0.0.
1484
1485.. code-block:: console
1486
1487   buffer-fail-fraction 0.0
1488
1489
1490tls Section
1491-----------
1492
1493Configures TLS parameters, such as enabling the use of test certificates.
1494These parameters affect the tlsmbedtls and tlsopenssl plugins.
1495
1496use-test-cert-in-ca
1497^^^^^^^^^^^^^^^^^^^
1498
1499Sets a boolean value to 1 to indicate during the initialization of a
1500TLS CA chain to attempt to parse and add test certificates to the chain.
1501Defaults to 0, meaning test certificates are not used.
1502
1503.. code-block:: console
1504
1505   use-test-cert-in-ca
1506
1507ca-cert-path <filename>
1508^^^^^^^^^^^^^^^^^^^^^^^
1509
1510Sets the filename path of the location of TLS CA certificates, used when
1511initializing and loading TLS CA certificates during the initialization
1512of a TLS CA chain. If not set, the default filename path is
1513*/etc/ssl/certs/ca-certificates.crt*.
1514
1515.. code-block:: console
1516
1517   ca-cert-path /etc/ssl/certs/ca-certificates.crt
1518
1519
1520tuntap Section
1521--------------
1522
1523The "tuntap" driver configures a point-to-point interface between the vpp
1524engine and the local Linux kernel stack. This allows e.g. users to ssh to the
1525host | VM | container via vpp "revenue" interfaces. It's marginally useful, and
1526is currently disabled by default. To [dynamically] create TAP interfaces - the
1527preferred scheme - see the "tap_connect" binary API. The Linux network stack
1528"vnet" interface needs to manually configure, and VLAN and other settings if
1529desired.
1530
1531
1532enable|disable
1533^^^^^^^^^^^^^^
1534
1535Enable or disable the tun/tap driver.
1536
1537.. code-block:: console
1538
1539   enable
1540
1541ethernet|ether
1542^^^^^^^^^^^^^^
1543
1544Create a tap device (ethernet MAC) instead of a tun device (point-to-point
1545tunnel). The two keywords are aliases for the same function.
1546
1547.. code-block:: console
1548
1549   ethernet
1550
1551have-normal-interface|have-normal
1552^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1553
1554Treat the host Linux stack as a routing peer instead of programming VPP
1555interface L3 addresses onto the tun/tap devices. The two keywords are
1556aliases for the same function.
1557
1558.. code-block:: console
1559
1560   have-normal-interface
1561
1562name <name>
1563^^^^^^^^^^^
1564
1565Assign name to the tun/tap device.
1566
1567.. code-block:: console
1568
1569   name vpp1
1570
1571
1572vhost-user Section
1573------------------
1574
1575Vhost-user configuration parameters control the vhost-user driver.
1576
1577coalesce-frames <n>
1578^^^^^^^^^^^^^^^^^^^
1579
1580Subject to deadline-timer expiration - see next item - attempt to transmit
1581at least <n> packet frames. Default is 32 frames.
1582
1583.. code-block:: console
1584
1585   coalesce-frames 64
1586
1587coalesce-time <seconds>
1588^^^^^^^^^^^^^^^^^^^^^^^
1589
1590Hold packets no longer than (floating-point) seconds before transmitting
1591them. Default is 0.001 seconds
1592
1593.. code-block:: console
1594
1595   coalesce-time 0.002
1596
1597dont-dump-memory
1598^^^^^^^^^^^^^^^^
1599
1600vhost-user shared-memory segments can add up to a large amount of memory, so
1601it's handy to avoid adding them to corefiles when using a significant number
1602of such interfaces.
1603
1604.. code-block:: console
1605
1606   dont-dump-memory
1607
1608
1609vlib Section
1610------------
1611
1612These parameters configure VLIB, such as allowing you to choose whether to
1613enable memory traceback or a post-mortem elog dump.
1614
1615memory-trace
1616^^^^^^^^^^^^
1617
1618Enables memory trace (mheap traceback.) Defaults to 0, meaning memory
1619trace is disabled.
1620
1621.. code-block:: console
1622
1623   memory-trace
1624
1625elog-events <n>
1626^^^^^^^^^^^^^^^
1627
1628Sets the number of elements/events (the size) of the event ring
1629(a circular buffer of events.) This number rounds to a power of 2.
1630Defaults to 131072 (128 << 10) elements.
1631
1632.. code-block:: console
1633
1634   elog-events 4096
1635
1636elog-post-mortem-dump
1637^^^^^^^^^^^^^^^^^^^^^
1638
1639Enables the attempt of a post-mortem elog dump to
1640*/tmp/elog_post_mortem.<PID_OF_CALLING_PROCESS>* if os_panic or
1641os_exit is called.
1642
1643.. code-block:: console
1644
1645   elog-post-mortem-dump
1646