blob: 8ce27eb676d6ae6cc94be4d5997af275dd550bed [file] [log] [blame]
John DeNisco06dcd452018-07-26 12:45:10 -04001.. _startup:
2
3
4.. toctree::
5
6
7=======================================
8VPP Configuration File - 'startup.conf'
9=======================================
10
11
12After a successful installation, VPP installs a startup config file named
John DeNiscoc64ba6d2018-08-02 15:03:15 -040013*startup.conf* in the */etc/vpp/* directory. This file can be tailored to
John DeNisco06dcd452018-07-26 12:45:10 -040014make VPP run as desired, but contains default values for typical installations.
John DeNiscoc64ba6d2018-08-02 15:03:15 -040015
16Below are more details about this file and the parameters and values it contains.
John DeNisco06dcd452018-07-26 12:45:10 -040017
18Introduction
19------------
20
21The VPP network stack comes with several configuration options that can be
22provided either on the command line when VPP is started, or in a configuration
23file. Specific applications built on the stack have been known to require a dozen
24arguments, depending on requirements.
25
26Command-line Arguments
27----------------------
28
29Parameters are grouped by a section name. When providing more than one
30parameter to a section, all parameters for that section must be wrapped in
31curly braces. For example, to start VPP with configuration data via the
32command line with the section name *'unix'*:
33
34.. code-block:: console
35
36 $ sudo /usr/bin/vpp unix { interactive cli-listen 127.0.0.1:5002 }
37
38The command line can be presented as a single string or as several; anything
39given on the command line is concatenated with spaces into a single string
40before parsing. VPP applications must be able to locate their own executable
41images. The simplest way to ensure this will work is to invoke a VPP
42application by giving its absolute path. For example:
43*'/usr/bin/vpp <options>'* At startup, VPP applications parse through their
44own ELF-sections [primarily] to make lists of init, configuration, and exit
45handlers.
46
47When developing with VPP, in gdb it's often sufficient to start an application
48like this:
49
50.. code-block:: console
51
52 (gdb) run unix interactive
53
54Configuration File
55------------------
56
57It is also possible to supply the configuration parameters in a startup
58configuration. The path of the file is provided to the VPP application on its
59command line. The format of the configuration file is a simple text file with
60the same content as the command line, but with the benefit of being able to use
61newlines to make the content easier to read. For example:
62
63.. code-block:: console
64
65 $ cat /etc/vpp/startup.conf
66 unix {
67 nodaemon
68 log /var/log/vpp/vpp.log
69 full-coredump
70 cli-listen localhost:5002
71 }
72
73 api-trace {
74 on
75 }
76
77 dpdk {
78 dev 0000:03:00.0
79 }
80
81VPP is then instructed to load this file with the -c option. For example:
82
83.. code-block:: console
84
85 $ sudo /usr/bin/vpp -c /etc/vpp/startup.conf
86
87When the VPP service is started, VPP is started with this option via another
88installed file, vpp.service (Ubuntu: /lib/systemd/system/vpp.service and
89CentOS: /usr/lib/systemd/system/vpp.service). See *'ExecStart'* below:
90
91.. code-block:: console
92
93 $ cat /lib/systemd/system/vpp.service
94 [Unit]
95 Description=vector packet processing engine
96 After=network.target
97
98 [Service]
99 Type=simple
100 ExecStartPre=-/bin/rm -f /dev/shm/db /dev/shm/global_vm /dev/shm/vpe-api
101 ExecStartPre=-/sbin/modprobe uio_pci_generic
102 ExecStart=/usr/bin/vpp -c /etc/vpp/startup.conf
103 ExecStopPost=/bin/rm -f /dev/shm/db /dev/shm/global_vm /dev/shm/vpe-api
104 Restart=always
105
106 [Install]
107 WantedBy=multi-user.target
108
109
110Configuration Parameters
111------------------------
112
113Below is the list of section names and their associated parameters. This is not
114an exhaustive list of parameters available. The command-line argument parsers
115can be found in the source code by searching for instances of the
116**VLIB_CONFIG_FUNCTION** and **VLIB_EARLY_CONFIG_FUNCTION** macro.
117
118For example, the invocation *'VLIB_CONFIG_FUNCTION (foo_config, "foo")'* will
119cause the function *'foo_config'* to receive all parameters given in a
120parameter block named "foo": "foo { arg1 arg2 arg3 ... }".
121
122
123List of Basic Parameters:
124-------------------------
125
126| unix_
127| dpdk_
128| cpu_
129
130List of Advanced Parameters:
131----------------------------
132
133| acl-plugin_
134| api-queue_
135| api-segment_
136| api-trace_
137| buffers_
138| cj_
139| dns_
140| heapsize_
141| ip_
142| ip6_
143| l2learn_
144| l2tp_
145| logging_
146| mactime_
147| map_
148| mc_
149| nat_
150| oam_
151| plugins_
152| plugin_path_
153| punt_
154| session_
155| socketsvr_
156| stats_
157| statseg_
158| tapcli_
159| tcp_
160| tls_
161| tuntap_
162| vhost-user_
163| vlib_
164
165.. _unix:
166
167"unix" Parameters
168_________________
169
170Configure VPP startup and behavior type attributes, as well and any OS based
171attributes.
172
173 * **interactive**
174 Attach CLI to stdin/out and provide a debugging command line interface.
175 Implies nodaemon.
176
177 **Example:** interactive
178
179 * **nodaemon**
180 Do not fork / background the vpp process. Typical when invoking VPP
181 applications from a process monitor. Set by default in the default
182 *'startup.conf'* file.
183
184 **Example:** nodaemon
185
186 * **log <filename>**
187 Logs the startup configuration and all subsequent CLI commands in filename.
188 Very useful in situations where folks don't remember or can't be bothered
189 to include CLI commands in bug reports. The default *'startup.conf'* file
190 is to write to *'/var/log/vpp/vpp.log'*.
191
192 In VPP 18.04, the default log file location was moved from '/tmp/vpp.log'
193 to '/var/log/vpp/vpp.log' . The VPP code is indifferent to the file location.
194 However, if SELinux is enabled, then the new location is required for the file
195 to be properly labeled. Check your local *'startup.conf'* file for the log file
196 location on your system.
197
198 **Example:** log /var/log/vpp/vpp-debug.log
199
200 * **exec|startup-config <filename>**
201 Read startup operational configuration from filename. The contents of the file
202 will be performed as though entered at the CLI. The two keywords are aliases
203 for the same function; if both are specified, only the last will have an effect.
204 The file contains CLI commands, for example:
205
206 | $ cat /usr/share/vpp/scripts/interface-up.txt
207 | set interface state TenGigabitEthernet1/0/0 up
208 | set interface state TenGigabitEthernet1/0/1 up
209
210 **Example:** startup-config /usr/share/vpp/scripts/interface-up.txt
211
212 * **gid number|name>**
213 Sets the effective group ID to the input group ID or group name of the calling
214 process.
215
216 **Example:** gid vpp
217
218 * **full-coredump**
219 Ask the Linux kernel to dump all memory-mapped address regions, instead of
220 just text+data+bss.
221
222 **Example:** full-coredump
223
224 * **coredump-size unlimited|<n>G|<n>M|<n>K|<n>**
225 Set the maximum size of the coredump file. The input value can be set in
226 GB, MB, KB or bytes, or set to *'unlimited'*.
227
228 **Example:** coredump-size unlimited
229
230 * **cli-listen <ipaddress:port>|<socket-path>**
231 Bind the CLI to listen at address localhost on TCP port 5002. This will
232 accept an ipaddress:port pair or a filesystem path; in the latter case a
233 local Unix socket is opened instead. The default *'startup.conf'* file
234 is to open the socket *'/run/vpp/cli.sock'*.
235
236 **Example:** cli-listen localhost:5002
237 **Example:** cli-listen /run/vpp/cli.sock
238
239 * **cli-line-mode**
240 Disable character-by-character I/O on stdin. Useful when combined with,
241 for example, emacs M-x gud-gdb.
242
243 **Example:** cli-line-mode
244
245 * **cli-prompt <string>**
246 Configure the CLI prompt to be string.
247
248 **Example:** cli-prompt vpp-2
249
250 * **cli-history-limit <n>**
251 Limit commmand history to <n> lines. A value of 0 disables command history.
252 Default value: 50
253
254 **Example:** cli-history-limit 100
255
256 * **cli-no-banner**
257 Disable the login banner on stdin and Telnet connections.
258
259 **Example:** cli-no-banner
260
261 * **cli-no-pager**
262 Disable the output pager.
263
264 **Example:** cli-no-pager
265
266 * **cli-pager-buffer-limit <n>**
267 Limit pager buffer to <n> lines of output. A value of 0 disables the
268 pager. Default value: 100000
269
270 **Example:** cli-pager-buffer-limit 5000
271
272 * **runtime-dir <dir>**
273 Set the runtime directory, which is the default location for certain
274 files, like socket files. Default is based on User ID used to start VPP.
275 Typically it is *'root'*, which defaults to *'/run/vpp/'*. Otherwise,
276 defaults to *'/run/user/<uid>/vpp/'*.
277
278 **Example:** runtime-dir /tmp/vpp
279
280 * **poll-sleep-usec <n>**
281 Add a fixed-sleep between main loop poll. Default is 0, which is not to
282 sleep.
283
284 **Example:** poll-sleep-usec 100
285
286 * **pidfile <filename>**
287 Writes the pid of the main thread in the given filename.
288
289 **Example:** pidfile /run/vpp/vpp1.pid
290
291.. _dpdk:
292
293"dpdk" Parameters
294_________________
295
296Command line DPDK configuration controls a number of parameters, including
297device whitelisting, the number of CPUs available for launching
298dpdk-eal-controlled threads, the number of I/O buffers, and the process
299affinity mask. In addition, the DPDK configuration function attempts to support
300all of the DPDK EAL configuration parameters.
301
302All of the DPDK EAL options should be available.
303See ../src/plugins/dpdk/device/dpdk_priv.h, look at the set of
304"foreach_eal_XXX" macros.
305
306Popular options include:
307 * **dev <pci-dev>**
308 White-list [as in, attempt to drive] a specific PCI device. PCI-dev is a
309 string of the form "DDDD:BB:SS.F" where:
310
311 | DDDD = Domain
312 | BB = Bus Number
313 | SS = Slot number
314 | F = Function
315
316 This is the same format used in the linux sysfs tree (i.e.
317 /sys/bus/pci/devices) for PCI device directory names.
318
319 **Example:** dev 0000:02:00.0
320
321 * **dev <pci-dev> { .. }**
322 When whitelisting specific interfaces by specifying PCI address,
323 additional custom parameters can also be specified. Valid options include:
324
325 * **num-rx-queues <n>**
326 Number of receive queues. Also enables RSS. Default value is 1.
327 * **num-tx-queues <n>**
328 Number of transmit queues. Default is equal to number of worker
329 threads or 1 if no workers treads.
330 * **num-rx-desc <n>**
331 Number of descriptors in receive ring. Increasing or reducing number
332 can impact performance. Default is 1024.
333 * **num-rt-desc <n>**
334 Number of descriptors in transmit ring. Increasing or reducing number
335 can impact performance. Default is 1024.
336 * **workers**
337 TBD
338 * **vlan-strip-offload on|off**:
339 VLAN strip offload mode for interface. VLAN stripping is off by default
340 for all NICs except VICs, using ENIC driver, which has VLAN stripping on
341 by default.
342 * **hqos**
343 Enable the Hierarchical Quaity-of-Service (HQoS) scheduler, default is
344 disabled. This enables HQoS on specific output interface.
345 * **hqos { .. }**
346 HQoS can also have its own set of custom parameters. Setting a custom
347 parameter also enables HQoS.
348
349 * **hqos-thread <n>**
350 HQoS thread used by this interface. To setup a pool of threads that
351 are shared by all HQoS interfaces, set via the*'cpu'* section using
352 either *'corelist-hqos-threads'* or *'coremask-hqos-threads'*.
353
354 * **rss**
355 TBD
356
357 **Example:**
358
359 | dev 0000:02:00.1 {
360 | num-rx-queues 2
361 | num-tx-queues 2
362 | }
363
364 * **vdev <eal-command>**
365 Provide a DPDK EAL command to specify bonded Ethernet interfaces, operating
366 modes and PCI addresses of slave links. Only XOR balanced (mode 2) mode is
367 supported.
368
369 **Example:**
370
371 | vdev eth_bond0,mode=2,slave=0000:0f:00.0,slave=0000:11:00.0,xmit_policy=l34
372 | vdev eth_bond1,mode=2,slave=0000:10:00.0,slave=0000:12:00.0,xmit_policy=l34
373
374 * **num-mbufs <n>**
375 Increase number of buffers allocated. May be needed in scenarios with
376 large number of interfaces and worker threads, or a lot of physical
377 interfaces with multiple RSS queues. Value is per CPU socket. Default is
378 16384.
379
380 **Example:** num-mbufs 128000
381
382 * **no-pci**
383 When VPP is started, if an interface is not owned by the linux kernel
384 (interface is administratively down), VPP will attempt to manage the
385 interface. *'no-pci'* indicates that VPP should not walk the PCI table
386 looking for interfaces.
387
388 **Example:** no-pci
389
390 * **no-hugetlb**
391 Don't use huge TLB pages. Potentially useful for running simulator images.
392
393 **Example:** no-hugetlb
394
395 * **kni <n>**
396 Number of KNI interfaces. Refer to the DPDK documentation.
397
398 **Example:** kni 2
399
400 * **uio-driver uio_pci_generic|igb_uio|vfio-pci|auto**
401 Change UIO driver used by VPP. Default is *'auto'*.
402
403 **Example:** uio-driver igb_uio
404
405 * **socket-mem <n>**
406 Change hugepages allocation per-socket, needed only if there is need for
407 larger number of mbufs. Default is 64 hugepages on each detected CPU
408 socket.
409
410 **Example:** socket-mem 2048,2048
411
412**Other options include:**
413
414 * **enable-tcp-udp-checksum**
415 Enables UDP/TCP RX checksum offload.
416
417 **Example:** enable-tcp-udp-checksum
418
419 * **no-multi-seg**
420 Disable mutli-segment buffers, improves performance but disables Jumbo MTU
421 support.
422
423 **Example:** no-multi-seg
424
425 * **no-tx-checksum-offload**
426 Disables UDP/TCP TX checksum offload. Typically needed for use faster
427 vector PMDs (together with no-multi-seg).
428
429 **Example:** no-tx-checksum-offload
430
431 * **decimal-interface-names**
432 Format DPDK device names with decimal, as opposed to hexadecimal.
433
434 **Example:** decimal-interface-names
435
436 * **log-level emergency|alert|critical|error|warning|notice|info|debug**
437 Set the log level for DPDK logs. Default is *'notice'*.
438
439 **Example:** log-level error
440
441 * **dev default { .. }**
442 Change default settings for all intefaces. This sections supports the
443 same set of custom parameters described in *'dev <pci-dev> { .. }*'.
444
445 **Example:**
446
447 | dev default {
448 | num-rx-queues 3
449 | num-tx-queues 3
450 | }
451
452.. _cpu:
453
454"cpu" Parameters
455________________
456
457Command-line CPU configuration controls the creation of named thread types, and
458the cpu affinity thereof. In the VPP there is one main thread and optionally
459the user can create worker(s). The main thread and worker thread(s) can be
460pinned to CPU core(s) automatically or manually.
461
462**Automatic Pinning:**
463
464 * **workers <n>**
465 Create <n> worker threads.
466
467 **Example:** workers 4
468
469 * **io <n>**
470 Create <n> i/o threads.
471
472 **Example:** io 2
473
474 * **main-thread-io**
475 Handle i/o devices from thread 0, hand off traffic to worker threads.
476 Requires "workers <n>".
477
478 **Example:** main-thread-io
479
480 * **skip-cores <n>**
481 Sets number of CPU core(s) to be skipped (1 ... N-1). Skipped CPU core(s)
482 are not used for pinning main thread and working thread(s). The main thread
483 is automatically pinned to the first available CPU core and worker(s) are
484 pinned to next free CPU core(s) after core assigned to main threadLeave
485 the low nn bits of the process affinity mask clear.
486
487 **Example:** skip-cores 4
488
489**Manual Pinning:**
490
491 * **main-core <n>**
492 Assign main thread to a specific core.
493
494 **Example:** main-core 1
495
496 * **coremask-workers <hex-mask>**
497 Place worker threads according to the bitmap hex-mask.
498
499 **Example:** coremask-workers 0x0000000000C0000C
500
501 * **corelist-workers <list>**
502 Same as coremask-workers but accepts a list of cores instead of a bitmap.
503
504 **Example:** corelist-workers 2-3,18-19
505
506 * **coremask-io <hex-mask>**
507 Place I/O threads according to the bitmap hex-mask.
508
509 **Example:** coremask-io 0x0000000003000030
510
511 * **corelist-io <list>**
512 Same as coremask-io but accepts a list of cores instead of a bitmap.
513
514 **Example:** corelist-io 4-5,20-21
515
516 * **coremask-hqos-threads <hex-mask>**
517 Place HQoS threads according to the bitmap hex-mask. A HQoS thread can
518 run multiple HQoS objects each associated with different output interfaces.
519
520 **Example:** coremask-hqos-threads 0x000000000C0000C0
521
522 * **corelist-hqos-threads <list>**
523 Same as coremask-hqos-threads but accepts a list of cores instead of a
524 bitmap.
525
526 **Example:** corelist-hqos-threads 6-7,22-23
527
528**Other:**
529
530 * **use-pthreads**
531 TBD
532
533 **Example:** use-pthreads
534
535 * **thread-prefix <prefix>**
536 Set a prefix to be prepended to each thread name. The thread name already
537 contains an underscore. If not provided, the default is *'vpp'*.
538 Currently, prefix used on threads: *'vpp_main'*, *'vpp_stats'*
539
540 **Example:** thread-prefix vpp1
541
542 * **scheduler-policy rr|fifo|batch|idle|other**
543 TBD
544
545 **Example:** scheduler-policy fifo
546
547 * **scheduler-priority <n>**
548 Set the scheduler priority. Only valid if the *'scheduler-policy'* is set
549 to *'fifo'* or *'rr'*. The valid ranges for the scheduler priority depends
550 on the *'scheduler-policy'* and the current kernel version running. The
551 range is typically 1 to 99, but see the linux man pages for *'sched'* for
552 more details. If this value is not set, the current linux kernel default
553 is left in place.
554
555 **Example:** scheduler-priority 50
556
557 * **<thread-name> <count>**
558 Set the number of threads for a given thread (by name). Some threads, like
559 *'stats'*, have a fixed number of threads and cannot be changed. List of
560 possible threads include (but not limited too): hqos-threads, workers
561
562 **Example:** hqos-threads 2
563
564.. note::
565
566 The "main" thread always occupies the lowest core-id specified in the
567 DPDK [process-level] coremask.
568
569Here's a full-bore manual placement example:
570
571.. code-block:: console
572
573 /usr/bin/vpp unix interactive tuntap disable cpu { main-thread-io coremask-workers 18 coremask-stats 4 } dpdk { coremask 1e }
574
575 # taskset -a -p <vpe-pid>
576 pid 16251's current affinity mask: 2 # main thread
577 pid 16288's current affinity mask: ffffff # DPDK interrupt thread (not bound to a core)
578 pid 16289's current affinity mask: 4 # stats thread
579 pid 16290's current affinity mask: 8 # worker thread 0
580 pid 16291's current affinity mask: 10 # worker thread 1
581
582
583.. _acl-plugin:
584
585"acl-plugin" Parameters
586_______________________
587
588The following parameters should only be set by those that are familiar with the
589interworkings of VPP and the ACL Plugin.
590
591The first three parameters, *connection hash buckets*, *connection hash memory*, and *connection count max*, set the **connection table per-interface parameters** for modifying how the two bounded-index extensible hash tables for IPv6 (40\*8 bit key and 8\*8 bit value pairs) and IPv4 (16\*8 bit key and 8\*8 bit value pairs) **ACL plugin FA interface sessions** are initialized.
592
593 * **connection hash buckets <n>**
594 Sets the number of hash buckets (rounded up to a power of 2) in each of the two bi-hash tables. Defaults to 64\*1024 (65536) hash buckets.
595
596 **Example:** connection hash buckets 65536
597
598 * **connection hash memory <n>**
599 Sets the number of bytes used for “backing store” allocation in each of the two bi-hash tables. Defaults to 1073741824 bytes.
600
601 **Example:** connection hash memory 1073741824
602
603 * **connection count max <n>**
604 Sets the maximum number of pool elements when allocating each per-worker pool of sessions for both bi-hash tables. Defaults to 500000 elements in each pool.
605
606 **Example:** connection count max 500000
607
608 * **main heap size <n>G|<n>M|<n>K|<n>**
609 Sets the size of the main memory heap that holds all the ACL module related allocations (other than hash.) Default size is 0, but during ACL heap initialization is equal to *per_worker_size_with_slack * tm->n_vlib_mains + bihash_size + main_slack*. Note that these variables are partially based on the **connection table per-interface parameters** mentioned above.
610
611 **Example:** main heap size 3G
612
613The next three parameters, *hash lookup heap size*, *hash lookup hash buckets*, and *hash lookup hash memory*, modify the initialization of the bi-hash lookup table used by the ACL plugin. This table is initialized when attempting to apply an ACL to the existing vector of ACLs looked up during packet processing (but it is found that the table does not exist / has not been initialized yet.)
614
615 * **hash lookup heap size <n>G|<n>M|<n>K|<n>**
616 Sets the size of the memory heap that holds all the miscellaneous allocations related to hash-based lookups. Default size is 67108864 bytes.
617
618 **Example:** hash lookup heap size 70M
619
620 * **hash lookup hash buckets <n>**
621 Sets the number of hash buckets (rounded up to a power of 2) in the bi-hash lookup table. Defaults to 65536 hash buckets.
622
623 **Example:** hash lookup hash buckets 65536
624
625 * **hash lookup hash memory <n>**
626 Sets the number of bytes used for “backing store” allocation in the bi-hash lookup table. Defaults to 67108864 bytes.
627
628 **Example:** hash lookup hash memory 67108864
629
630 * **use tuple merge <n>**
631 Sets a boolean value indicating whether or not to use TupleMerge for hash ACL's. Defaults to 1 (true), meaning the default implementation of hashing ACL's **does use** TupleMerge.
632
633 **Example:** use tuple merge 1
634
635 * **tuple merge split threshold <n>**
636 Sets the maximum amount of rules (ACE's) that can collide in a bi-hash lookup table before the table is split into two new tables. Splitting ensures less rule collisions by hashing colliding rules based on their common tuple (usually their maximum common tuple.) Splitting occurs when the *length of the colliding rules vector* is greater than this threshold amount. Defaults to a maximum of 39 rule collisions per table.
637
638 **Example:** tuple merge split threshold 30
639
640 * **reclassify sessions <n>**
641 Sets a boolean value indicating whether or not to take the epoch of the session into account when dealing with re-applying ACL's or changing already applied ACL's. Defaults to 0 (false), meaning the default implementation **does NOT** take the epoch of the session into account.
642
643 **Example:** reclassify sessions 1
644
645.. _api-queue:
646
647"api-queue" Parameters
648______________________
649
650The following parameters should only be set by those that are familiar with the
651interworkings of VPP.
652
653 * **length <n>**
654 Sets the api queue length. Minimum valid queue length is 1024, which is
655 also the default.
656
657 **Example:** length 2048
658
659.. _api-segment:
660
661"api-segment" Parameters
662________________________
663
664These values control various aspects of the binary API interface to VPP.
665
666 * **prefix <path>**
667 Sets the prefix prepended to the name used for shared memory (SHM)
668 segments. The default is empty, meaning shared memory segments are created
669 directly in the SHM directory *'/dev/shm'*. It is worth noting that on
670 many systems *'/dev/shm'* is a symbolic link to somewhere else in the file
671 system; Ubuntu links it to *'/run/shm'*.
672
673 **Example:** prefix /run/shm
674
675 * **uid <number|name>**
676 Sets the user ID or name that should be used to set the ownership of the
677 shared memory segments. Defaults to the same user that VPP is started
678 with, probably root.
679
680 **Example:** uid root
681
682 * **gid <number|name>**
683 Sets the group ID or name that should be used to set the ownership of the
684 shared memory segments. Defaults to the same group that VPP is started
685 with, probably root.
686
687 **Example:** gid vpp
688
689The following parameters should only be set by those that are familiar with the
690interworkings of VPP.
691
692 * **baseva <x>**
693 Set the base address for SVM global region. If not set, on AArch64, the
694 code will try to determine the base address. All other default to
695 0x30000000.
696
697 **Example:** baseva 0x20000000
698
699 * **global-size <n>G|<n>M|<n>**
700 Set the global memory size, memory shared across all router instances,
701 packet buffers, etc. If not set, defaults to 64M. The input value can be
702 set in GB, MB or bytes.
703
704 **Example:** global-size 2G
705
706 * **global-pvt-heap-size <n>M|size <n>**
707 Set the size of the global VM private mheap. If not set, defaults to 128k.
708 The input value can be set in MB or bytes.
709
710 **Example:** global-pvt-heap-size size 262144
711
712 * **api-pvt-heap-size <n>M|size <n>**
713 Set the size of the api private mheap. If not set, defaults to 128k.
714 The input value can be set in MB or bytes.
715
716 **Example:** api-pvt-heap-size 1M
717
718 * **api-size <n>M|<n>G|<n>**
719 Set the size of the API region. If not set, defaults to 16M. The input
720 value can be set in GB, MB or bytes.
721
722 **Example:** api-size 64M
723
724.. _api-trace:
725
726"api-trace" Parameters
727______________________
728
729The ability to trace, dump, and replay control-plane API traces makes all the
730difference in the world when trying to understand what the control-plane has
731tried to ask the forwarding-plane to do.
732
733 * **on|enable**
734 Enable API trace capture from the beginning of time, and arrange for a
735 post-mortem dump of the API trace if the application terminates abnormally.
736 By default, the (circular) trace buffer will be configured to capture
737 256K traces. The default *'startup.conf'* file has trace enabled by default,
738 and unless there is a very strong reason, it should remain enabled.
739
740 **Example:** on
741
742 * **nitems <n>**
743 Configure the circular trace buffer to contain the last <n> entries. By
744 default, the trace buffer captures the last 256K API messages received.
745
746 **Example:** nitems 524288
747
748 * **save-api-table <filename>**
749 Dumps the API message table to /tmp/<filename>.
750
751 **Example:** save-api-table apiTrace-07-04.txt
752
753Typically, one simply enables the API message trace scheme:
754
755 api-trace { on }
756
757.. _buffers:
758
759"buffers" Parameters
760____________________
761
762Command line Buffer configuration controls buffer management.
763
764 * **memory-size-in-mb <n>**
765 Configure the memory size used for buffers. If not set, VPP defaults
766 to 32MB.
767
768 **Example:** memory-size-in-mb 64
769
770
771.. _cj:
772
773"cj" Parameters
774_______________
775
776The circular journal (CJ) thread-safe circular log buffer scheme is
777occasionally useful when chasing bugs. Calls to it should not be checked in.
778See .../vlib/vlib/unix/cj.c. The circular journal is disables by default.
779When enabled, the number of records must be provided, there is no default
780value.
781
782 * **records <n>**
783 Configure the number of circular journal records in the circular buffer.
784 The number of records should be a power of 2.
785
786 **Example:** records 131072
787
788 * **on**
789 Turns on logging at the earliest possible moment.
790
791 **Example:** on
792
793.. _dns:
794
795"dns" Parameters
796________________
797
798 * **max-cache-size <n>**
799 TBD
800
801 **Example:** TBD
802
803 * **max-ttl <n>**
804 TBD
805
806 **Example:** TBD
807
808.. _heapsize:
809
810"heapsize" Parameters
811_____________________
812
813Heapsize configuration controls the size of the main heap. The heap size is
814configured very early in the boot sequence, before loading plug-ins or doing
815much of anything else.
816
817 * **heapsize <n>M|<n>G**
818 Specifies the size of the heap in MB or GB. The default is 1GB. Setting the
819 main heap size to 4GB or more requires recompilation of the entire system
820 with CLIB_VEC64 > 0. See .../clib/clib/vec_bootstrap.h.
821
822 **Example:** heapsize 2G
823
824.. _ip:
825
826"ip" Parameters
827_______________
828
829IPv4 heap configuration. he heap size is configured very early in the boot
830sequence, before loading plug-ins or doing much of anything else.
831
832 * **heap-size <n>G|<n>M|<n>K|<n>**
833 Set the IPv4 mtrie heap size, which is the amount of memory dedicated to
834 the destination IP lookup table. The input value can be set in GB, MB, KB
835 or bytes. The default value is 32MB.
836
837 **Example:** heap-size 64M
838
839.. _ip6:
840
841"ip6" Parameters
842________________
843
844IPv6 heap configuration. he heap size is configured very early in the boot
845sequence, before loading plug-ins or doing much of anything else.
846
847
848 * **heap-size <n>G|<n>M|<n>K|<n>**
849 Set the IPv6 forwarding table heap size. The input value can be set in GB,
850 MB, KB or bytes. The default value is 32MB.
851
852 **Example:** heap-size 64M
853
854 * **hash-buckets <n>**
855 Set the number of IPv6 forwarding table hash buckets. The default value is
856 64K (65536).
857
858 **Example:** hash-buckets 131072
859
860.. _l2learn:
861
862"l2learn" Parameters
863____________________
864
865Configure Layer 2 MAC Address learning parameters.
866
867 * **limit <n>**
868 Configures the number of L2 (MAC) addresses in the L2 FIB at any one time,
869 which limits the size of the L2 FIB to <n> concurrent entries. Defaults to
870 4M entries (4194304).
871
872 **Example:** limit 8388608
873
874.. _l2tp:
875
876"l2tp" Parameters
877_________________
878
879IPv6 Layer 2 Tunnelling Protocol Version 3 (IPv6-L2TPv3) configuration controls
880the method used to locate a specific IPv6-L2TPv3 tunnel. The following settings
881are mutually exclusive:
882
883 * **lookup-v6-src**
884 Lookup tunnel by IPv6 source address.
885
886 **Example:** lookup-v6-src
887
888 * **lookup-v6-dst**
889 Lookup tunnel by IPv6 destination address.
890
891 **Example:** lookup-v6-dst
892
893 * **lookup-session-id**
894 Lookup tunnel by L2TPv3 session identifier.
895
896 **Example:** lookup-session-id
897
898.. _logging:
899
900"logging" Parameters
901____________________
902
903 * **size <n>**
904 TBD
905
906 **Example:** TBD
907
908 * **unthrottle-time <n>**
909 TBD
910
911 **Example:** TBD
912
913 * **default-log-level emerg|alertcrit|err|warn|notice|info|debug|disabled**
914 TBD
915
916 **Example:** TBD
917
918 * **default-syslog-log-level emerg|alertcrit|err|warn|notice|info|debug|disabled**
919 TBD
920
921 **Example:** TBD
922
923.. _mactime:
924
925"mactime" Parameters
926____________________
927
928 * **lookup-table-buckets <n>**
929 TBD
930
931 **Example:** TBD
932
933 * **lookup-table-memory <n>G|<n>M|<n>K|<n>**
934 TBD
935 The input value can be set in GB, MB, KB or bytes. The default value is 256KB.
936
937 **Example:** TBD
938
939 * **timezone_offset <n>**
940 TBD
941
942 **Example:** TBD
943
944.. _map:
945
946"map" Parameters
947________________
948
949 * **customer edge**
950 TBD
951
952 **Example:** customer edge
953
954.. _mc:
955
956"mc" Parameters
957_______________
958
959MC Test Process.
960
961 * **interface <name>**
962 TBD
963
964 **Example:** TBD
965
966 * **n-bytes <n>**
967 TBD
968
969 **Example:** TBD
970
971 * **max-n-bytes <n>**
972 TBD
973
974 **Example:** TBD
975
976 * **min-n-bytes <n>**
977 TBD
978
979 **Example:** TBD
980
981 * **seed <n>**
982 TBD
983
984 **Example:** TBD
985
986 * **window <n>**
987 TBD
988
989 **Example:** TBD
990
991 * **verbose**
992 TBD
993
994 **Example:** verbose
995
996 * **no-validate**
997 TBD
998
999 **Example:** no-validate
1000
1001 * **min-delay <n.n>**
1002 TBD
1003
1004 **Example:** TBD
1005
1006 * **max-delay <n.n>**
1007 TBD
1008
1009 **Example:** TBD
1010
1011 * **no-delay**
1012 TBD
1013
1014 **Example:** no-delay
1015
1016 * **n-packets <n.n>**
1017 TBD
1018
1019 **Example:** TBD
1020
1021.. _nat:
1022
1023
1024"nat" Parameters
1025________________
1026
1027 * **translation hash buckets <n>**
1028 TBD
1029
1030 **Example:** TBD
1031
1032 * **translation hash memory <n>**
1033 TBD
1034
1035 **Example:** TBD
1036
1037 * **user hash buckets <n>**
1038 TBD
1039
1040 **Example:** TBD
1041
1042 * **user hash memory <n>**
1043 TBD
1044
1045 **Example:** TBD
1046
1047 * **max translations per user <n>**
1048 TBD
1049
1050 **Example:** TBD
1051
1052 * **outside VRF id <n>**
1053 TBD
1054
1055 **Example:** TBD
1056
1057 * **outside ip6 VRF id <n>**
1058 TBD
1059
1060 **Example:** TBD
1061
1062 * **inside VRF id <n>**
1063 TBD
1064
1065 **Example:** TBD
1066
1067 * **inside VRF id <n>**
1068 TBD
1069
1070 **Example:** TBD
1071
1072 * **static mapping only**
1073 TBD
1074
1075 **Example:** static mapping only
1076
1077 * **connection tracking**
1078 TBD
1079
1080 **Example:** connection tracking
1081
1082 * **deterministic**
1083 TBD
1084
1085 **Example:** deterministic
1086
1087 * **nat64 bib hash buckets <n>**
1088 TBD
1089
1090 **Example:** TBD
1091
1092 * **nat64 bib hash memory <n>**
1093 TBD
1094
1095 **Example:** TBD
1096
1097 * **nat64 st hash buckets <n>**
1098 TBD
1099
1100 **Example:** TBD
1101
1102 * **nat64 st hash memory <n>**
1103 TBD
1104
1105 **Example:** TBD
1106
1107 * **out2in dpo**
1108 TBD
1109
1110 **Example:** out2in dpo
1111
1112 * **dslite ce**
1113 TBD
1114
1115 **Example:** dslite ce
1116
1117 * **endpoint-dependent**
1118 TBD
1119
1120 **Example:** endpoint-dependent
1121
1122.. _oam:
1123
1124"oam" Parameters
1125________________
1126
1127OAM configuration controls the (ip4-icmp) interval, and number of misses
1128allowed before reporting an oam target down to any registered listener.
1129
1130 * **interval <n.n>**
1131 Interval, floating-point seconds, between sending OAM IPv4 ICMP messages.
1132 Default is 2.04 seconds.
1133
1134 **Example:** interval 3.5
1135
1136 * **misses-allowed <n>**
1137 Number of misses before declaring an OAM target down. Default is 3 misses.
1138
1139 **Example:** misses-allowed 5
1140
1141.. _plugins:
1142
1143"plugins" Parameters
1144____________________
1145A plugin can be disabled by default. It may still be in an experimental phase
1146or only be needed in special circumstances. If this is the case, the plugin can
1147be explicitely enabled in *'startup.conf'*. Also, a plugin that is enabled by
1148default can be explicitely disabled in *'startup.conf'*.
1149
1150Another useful use of this section is to disable all the plugins, then enable
1151only the plugins that are desired.
1152
1153 * **path <path>**
1154 Adjust the plugin path depending on where the VPP plugins are installed.
1155
1156 **Example:** path /home/bms/vpp/build-root/install-vpp-native/vpp/lib64/vpp_plugins
1157
1158 * **name-filter <filter-name>**
1159 TBD
1160
1161 **Example:** TBD
1162
1163 * **vat-path <path>**
1164 TBD
1165
1166 **Example:** TBD
1167
1168 * **vat-name-filter <filter-name>**
1169 TBD
1170
1171 **Example:** TBD
1172
1173 * **plugin <plugin.so> { .. }**
1174 Configure parameters for a given plugin. Valid parameters are as follows:
1175
1176 * **enable**
1177 Enable the given plugin.
1178 * **disable**
1179 Disable the given plugin.
1180 * **skip-version-check**
1181 In the plugin registration, if *'.version_required'* is set, the
1182 plugin will not be loaded if there is version mismatch between
1183 plugin and VPP. This can be bypassed by setting "skip-version-check"
1184 for specific plugin.
1185
1186 **Example:** plugin ila_plugin.so { enable skip-version-check }
1187
1188 * **plugin default { .. }**
1189 Set the default behavior for all plugins. Valid parameters are as follows:
1190
1191 * **disable**
1192 Disable all plugins.
1193
1194 **Example:**
1195 | plugin default { disable }
1196 | plugin dpdk_plugin.so { enable }
1197 | plugin acl_plugin.so { enable }
1198
1199.. _plugin_path:
1200
1201"plugin_path" Parameters
1202________________________
1203
1204Alternate syntax to choose plugin path. Plugin_path configuration controls the
1205set of directories searched for vlib plugins. Supply a colon-separated list of
1206(absolute) directory names: plugin_path dir1:dir2:...:dirN
1207
1208 **Example:** plugin_path /home/bms/vpp/build-root/install-vpp-native/vpp/lib64/vpp_plugins
1209
1210.. _punt:
1211
1212"punt" Parameters
1213_________________
1214
1215 * **socket <path>**
1216 TBD
1217
1218 **Example:** TBD
1219
1220.. _session:
1221
1222"session" Parameters
1223____________________
1224
1225 * **event-queue-length <n>**
1226 TBD
1227
1228 **Example:** TBD
1229
1230 * **preallocated-sessions <n>**
1231 TBD
1232
1233 **Example:** TBD
1234
1235 * **v4-session-table-buckets <n>**
1236 TBD
1237
1238 **Example:** TBD
1239
1240 * **v4-halfopen-table-buckets <n>**
1241 TBD
1242
1243 **Example:** TBD
1244
1245 * **v6-session-table-buckets <n>**
1246 TBD
1247
1248 **Example:** TBD
1249
1250 * **v6-halfopen-table-buckets <n>**
1251 TBD
1252
1253 **Example:** TBD
1254
1255 * **v4-session-table-memory <n>G|<n>M|<n>K|<n>**
1256 TBD
1257 The input value can be set in GB, MB, KB or bytes.
1258
1259 **Example:** TBD
1260
1261 * **v4-halfopen-table-memory <n>G|<n>M|<n>K|<n>**
1262 TBD
1263 The input value can be set in GB, MB, KB or bytes.
1264
1265 **Example:** TBD
1266
1267 * **v6-session-table-memory <n>G|<n>M|<n>K|<n>**
1268 TBD
1269 The input value can be set in GB, MB, KB or bytes.
1270
1271 **Example:** TBD
1272
1273 * **v6-halfopen-table-memory <n>G|<n>M|<n>K|<n>**
1274 TBD
1275 The input value can be set in GB, MB, KB or bytes.
1276
1277 **Example:** TBD
1278
1279 * **local-endpoints-table-memory <n>G|<n>M|<n>K|<n>**
1280 TBD
1281 The input value can be set in GB, MB, KB or bytes.
1282
1283 **Example:** TBD
1284
1285 * **local-endpoints-table-buckets <n>**
1286 TBD
1287
1288 **Example:** TBD
1289
1290 * **evt_qs_memfd_seg**
1291 TBD
1292
1293 **Example:** evt_qs_memfd_seg
1294
1295.. _socketsvr:
1296
1297"socketsvr" Parameters
1298______________________
1299
1300Create a socket server for API server (.../vlibmemory/socksvr_vlib.c.).
1301If not set, API server doesn't run.
1302
1303 * **socket-name <filename>**
1304 Configure API socket filename.
1305
1306 **Example:** socket-name /run/vpp/vpp-api.sock
1307
1308 * **default**
1309 Use the default API socket (/run/vpp-api.sock).
1310
1311 **Example:** default
1312
1313.. _stats:
1314
1315"stats" Parameters
1316__________________
1317
1318Create a socket server for *'stats'* poller. If not set, 'stats'* poller
1319doesn't run.
1320
1321 * **socket-name <filename>**
1322 Configure *'stats'* socket filename.
1323
1324 **Example:** socket-name /run/vpp/stats.sock
1325
1326 * **default**
1327 Use the default *'stats'* socket (/run/vpp/stats.sock).
1328
1329 **Example:** default
1330
1331.. _statseg:
1332
1333"statseg" Parameters
1334____________________
1335
1336 * **size <n>G|<n>M|<n>K|<n>**
1337 TBD
1338 The input value can be set in GB, MB, KB or bytes.
1339
1340 **Example:** TBD
1341
1342.. _tapcli:
1343
1344"tapcli" Parameters
1345___________________
1346
1347 * **mtu <n>**
1348 TBD
1349
1350 **Example:** TBD
1351
1352 * **disable**
1353 TBD
1354
1355 **Example:** disable
1356
1357.. _tcp:
1358
1359"tcp" Parameters
1360________________
1361
1362 * **preallocated-connections <n>**
1363 TBD
1364
1365 **Example:** TBD
1366
1367 * **preallocated-half-open-connections <n>**
1368 TBD
1369
1370 **Example:** TBD
1371
1372 * **buffer-fail-fraction <n.n>**
1373 TBD
1374
1375 **Example:** TBD
1376
1377.. _tls:
1378
1379"tls" Parameters
1380________________
1381
1382 * **se-test-cert-in-ca**
1383 TBD
1384
1385 **Example:** se-test-cert-in-ca
1386
1387 * **ca-cert-path <filename>**
1388 TBD
1389 If not set, the default is set to *'/etc/ssl/certs/ca-certificates.crt'*.
1390
1391 **Example:** TBD
1392
1393.. _tuntap:
1394
1395"tuntap" Parameters
1396___________________
1397
1398The "tuntap" driver configures a point-to-point interface between the vpp
1399engine and the local Linux kernel stack. This allows e.g. users to ssh to the
1400host | VM | container via vpp "revenue" interfaces. It's marginally useful, and
1401is currently disabled by default. To [dynamically] create TAP interfaces - the
1402preferred scheme - see the "tap_connect" binary API. The Linux network stack
1403"vnet" interface needs to manually configure, and VLAN and other settings if
1404desired.
1405
1406 * **enable|disable**
1407 Enable or disable the tun/tap driver.
1408
1409 **Example:** enable
1410
1411 * **ethernet|ether**
1412 Create a tap device (ethernet MAC) instead of a tun device (point-to-point
1413 tunnel). The two keywords are aliases for the same function.
1414
1415 **Example:** ethernet
1416
1417 * **have-normal-interface|have-normal**
1418 Treat the host Linux stack as a routing peer instead of programming VPP
1419 interface L3 addresses onto the tun/tap devices. The two keywords are
1420 aliases for the same function.
1421
1422 **Example:** have-normal-interface
1423
1424 * **name <name>**
1425 Assign name to the tun/tap device.
1426
1427 **Example:** name vpp1
1428
1429Here's a typical multiple parameter invocation:
1430
1431 | tuntap { ethernet have-normal-interface name vpp1 }
1432
1433.. _vhost-user:
1434
1435"vhost-user" Parameters
1436_______________________
1437
1438Vhost-user configuration parameters control the vhost-user driver.
1439
1440 * **coalesce-frames <n>**
1441 Subject to deadline-timer expiration - see next item - attempt to transmit
1442 at least <n> packet frames. Default is 32 frames.
1443
1444 **Example:** coalesce-frames 64
1445
1446 * **coalesce-time <seconds>**
1447 Hold packets no longer than (floating-point) seconds before transmitting
1448 them. Default is 0.001 seconds
1449
1450 **Example:** coalesce-time 0.002
1451
1452 * **dont-dump-memory**
1453 vhost-user shared-memory segments can add up to a large amount of memory, so
1454 it's handy to avoid adding them to corefiles when using a significant number
1455 of such interfaces.
1456
1457 **Example:** dont-dump-memory
1458
1459.. _vlib:
1460
1461"vlib" Parameters
1462_________________
1463
1464 * **memory-trace**
1465 TBD
1466
1467 **Example:** memory-trace
1468
1469 * **elog-events <n>**
1470 TBD
1471
1472 **Example:** TBD
1473
1474 * **elog-post-mortem-dump**
1475 TBD
1476
1477 **Example:** elog-post-mortem-dump
1478