docs/configuration/config_getting_started.rst


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

.. _config_getting_started:

=======================================
Getting started with the configuration
=======================================

After a successful installation, VPP installs a startup config file named
*startup.conf* in the */etc/vpp/* directory. This file can be tailored to
make VPP run as desired, but contains default values for typical installations.

Below are more details about this file and some of the the parameters and values
it contains.

Command-line Arguments
----------------------

Before we describe details of the startup configuration file (startup.conf) it
should be mentioned that VPP can be started without a startup configuration
file.

Parameters are grouped by a section name. When providing more than one
parameter to a section, all parameters for that section must be wrapped in
curly braces. For example, to start VPP with configuration data via the
command line with the section name *'unix'*:

.. code-block:: console

    $ sudo /usr/bin/vpp unix { interactive cli-listen 127.0.0.1:5002 }

The command line can be presented as a single string or as several; anything
given on the command line is concatenated with spaces into a single string
before parsing. VPP applications must be able to locate their own executable
images. The simplest way to ensure this will work is to invoke a VPP
application by giving its absolute path. For example:
*'/usr/bin/vpp <options>'*  At startup, VPP applications parse through their
own ELF-sections [primarily] to make lists of init, configuration, and exit
handlers.

When developing with VPP, in gdb it's often sufficient to start an application
like this:

.. code-block:: console

    (gdb) run unix interactive


Configuration File (startup.conf)
-----------------------------------------

The more typical way to specify the startup configuration to VPP is with the
startup configuration file (startup.conf).

The path of the file is provided to the VPP application on the command line.
This is typically at /etc/vpp/startup.conf. If VPP is installed as a package
a default startup.conf file is provided at this location.

The format of the configuration file is a simple text file with the same content
as the command line.

**A very simple startup.conf file:**

.. code-block:: console

    $ cat /etc/vpp/startup.conf
    unix {
      nodaemon
      log /var/log/vpp/vpp.log
      full-coredump
      cli-listen localhost:5002
    }

    api-trace {
      on
    }

    dpdk {
      dev 0000:03:00.0
    }

VPP is instructed to load this file with the -c option. For example:

.. code-block:: console

    $ sudo /usr/bin/vpp -c /etc/vpp/startup.conf
/* Hey Emacs use -*- mode: C -*- */
/*
 * Copyright (c) 2016 Cisco and/or its affiliates.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at:
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/** \file
    This file defines the vpp control-plane API messages
    used to control the ACL plugin
*/

option version = "2.0.0";

import "plugins/acl/acl_types.api";
import "vnet/interface_types.api";

/** \brief Get the plugin version
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
*/

define acl_plugin_get_version
{
  u32 client_index;
  u32 context;
};

/** \brief Reply to get the plugin version
    @param context - returned sender context, to match reply w/ request
    @param major - Incremented every time a known breaking behavior change is introduced
    @param minor - Incremented with small changes, may be used to avoid buggy versions
*/

define acl_plugin_get_version_reply
{
  u32 context;
  u32 major;
  u32 minor;
};

/** \brief Control ping from client to api server request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
*/
define acl_plugin_control_ping
{
  u32 client_index;
  u32 context;
};

/** \brief Control ping from the client to the server response
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param retval - return code for the request
    @param vpe_pid - the pid of the vpe, returned by the server
*/
define acl_plugin_control_ping_reply
{
  u32 context;
  i32 retval;
  u32 client_index;
  u32 vpe_pid;
};

/** \brief Get Connection table max entries
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
*/

define acl_plugin_get_conn_table_max_entries
{
  u32 client_index;
  u32 context;
};

/** \brief Reply to get connection table max entries
    @param context - sender context, to match reply w/ request
    @param conn_table_max_entries - the value of maximum entries of connection table
*/
define acl_plugin_get_conn_table_max_entries_reply
{
  u32 context;
  u64 conn_table_max_entries;
};

/** \brief Replace an existing ACL in-place or create a new ACL
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param acl_index - an existing ACL entry (0..0xfffffffe) to replace, or 0xffffffff to make new ACL
    @param tag - a string value stored along with the ACL, for descriptive purposes
    @param count - number of ACL rules
    @r - Rules for this access-list
*/

manual_print manual_endian define acl_add_replace
{
  u32 client_index;
  u32 context;
  u32 acl_index; /* ~0 to add, existing ACL# to replace */
  string tag[64]; /* What gets in here gets out in the corresponding tag field when dumping the ACLs. */
  u32 count;
  vl_api_acl_rule_t r[count];
  option vat_help = "<acl-idx> [<ipv4|ipv6>] <permit|permit+reflect|deny|action N> [src IP/plen] [dst IP/plen] [sport X-Y] [dport X-Y] [proto P] [tcpflags FL MASK], ... , ...";
};

/** \brief Reply to add/replace ACL
    @param context - returned sender context, to match reply w/ request
    @param acl_index - index of the updated or newly created ACL
    @param retval 0 - no error
*/

define acl_add_replace_reply
{
  u32 context;
  u32 acl_index;
  i32 retval;
};

/** \brief Delete an ACL
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param acl_index - ACL index to delete
*/

autoreply manual_print define acl_del
{
  u32 client_index;
  u32 context;
  u32 acl_index;
  option vat_help = "<acl-idx>";
};

/* acl_interface_add_del(_reply) to be deprecated in lieu of acl_interface_set_acl_list */
/** \brief Use acl_interface_set_acl_list instead
    Append/remove an ACL index to/from the list of ACLs checked for an interface
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param is_add - add or delete the ACL index from the list
    @param is_input - check the ACL on input (1) or output (0)
    @param sw_if_index - the interface to alter the list of ACLs on
    @param acl_index - index of ACL for the operation
*/

autoreply manual_print define acl_interface_add_del
{
  u32 client_index;
  u32 context;
  bool is_add [default=true];
/*
 * is_input = 0 => ACL applied on interface egress
 * is_input = 1 => ACL applied on interface ingress
 */
  bool is_input;
  vl_api_interface_index_t sw_if_index;
  u32 acl_index;
  option vat_help = "<intfc> | sw_if_index <if-idx> [add|del] [input|output] acl <acl-idx>";
};

/** \brief Set the vector of input/output ACLs checked for an interface
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - the interface to alter the list of ACLs on
    @param count - total number of ACL indices in the vector
    @param n_input - this many first elements correspond to input ACLs, the rest - output
    @param acls - vector of ACL indices
*/

autoreply manual_print define acl_interface_set_acl_list
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u8 count;
  u8 n_input; /* First n_input ACLs are set as a list of input ACLs, the rest are applied as output */
  u32 acls[count];
  option vat_help = "<intfc> | sw_if_index <if-idx> input [acl-idx list] output [acl-idx list]";
};

/** \brief Reply to set the ACL list on an interface
    @param context - returned sender context, to match reply w/ request
    @param retval 0 - no error
*/

/** \brief Dump the specific ACL contents or all of the ACLs' contents
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param acl_index - ACL index to dump, ~0 to dump all ACLs
*/

define acl_dump
{
  u32 client_index;
  u32 context;
  u32 acl_index; /* ~0 for all ACLs */
  option vat_help = "[<acl-idx>]";
};

/** \brief Details about a single ACL contents
    @param context - returned sender context, to match reply w/ request
    @param acl_index - ACL index whose contents are being sent in this message
    @param tag - Descriptive tag value which was supplied at ACL creation
    @param count - Number of rules in this ACL
    @param r - Array of rules within this ACL
*/

manual_endian manual_print define acl_details
{
  u32 context;
  u32 acl_index;
  string tag[64]; /* Same blob that was supplied to us when creating the ACL, one hopes. */
  u32 count;
  vl_api_acl_rule_t r[count];
};

/** \brief Dump the list(s) of ACL applied to specific or all interfaces
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - interface to dump the ACL list for
*/

define acl_interface_list_dump
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index; /* ~0 for all interfaces */
  option vat_help = "[<intfc> | sw_if_index <if-idx>]";
};

/** \brief Details about a single ACL contents
    @param context - returned sender context, to match reply w/ request
    @param sw_if_index - interface for which the list of ACLs is applied
    @param count - total length of acl indices vector
    @param n_input - this many of indices in the beginning are input ACLs, the rest - output
    @param acls - the vector of ACL indices
*/

define acl_interface_list_details
{
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u8 count;
  u8 n_input;
  u32 acls[count];
};

/** \brief Add a MACIP ACL
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param tag - descriptive value for this MACIP ACL
    @param count - number of rules in this MACIP ACL
    @param r - vector of MACIP ACL rules
*/

manual_endian manual_print define macip_acl_add
{
  u32 client_index;
  u32 context;
  string tag[64];
  u32 count;
  vl_api_macip_acl_rule_t r[count];
  option vat_help = "...";
};

/** \brief Reply to add MACIP ACL
    @param context - returned sender context, to match reply w/ request
    @param acl_index - index of the newly created MACIP ACL
    @param retval 0 - no error
*/

define macip_acl_add_reply
{
  u32 context;
  u32 acl_index;
  i32 retval;
};

/** \brief Add/Replace a MACIP ACL
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param acl_index - an existing MACIP ACL entry (0..0xfffffffe) to replace, or 0xffffffff to make new MACIP ACL
    @param tag - descriptive value for this MACIP ACL
    @param count - number of rules in this MACIP ACL
    @param r - vector of MACIP ACL rules
*/

manual_endian manual_print define macip_acl_add_replace
{
  u32 client_index;
  u32 context;
  u32 acl_index; /* ~0 to add, existing MACIP ACL# to replace */
  string tag[64];
  u32 count;
  vl_api_macip_acl_rule_t r[count];
  option vat_help = "<acl-idx> [<ipv4|ipv6>] <permit|deny|action N> [count <count>] [src] ip <ipaddress/[plen]> mac <mac> mask <mac_mask>, ... , ...";
};

/** \brief Reply to add/replace MACIP ACL
    @param context - returned sender context, to match reply w/ request
    @param acl_index - index of the newly created MACIP ACL
    @param retval 0 - no error
*/

define macip_acl_add_replace_reply
{
  u32 context;
  u32 acl_index;
  i32 retval;
};

/** \brief Delete a MACIP ACL
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param acl_index - MACIP ACL index to delete
*/

autoreply manual_print define macip_acl_del
{
  u32 client_index;
  u32 context;
  u32 acl_index;
  option vat_help = "<acl-idx>";
};

/** \brief Add or delete a MACIP ACL to/from interface
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param is_add - add (1) or delete (0) MACIP ACL from being used on an interface
    @param sw_if_index - interface to apply the action to
    @param acl_index - MACIP ACL index
*/

autoreply manual_print define macip_acl_interface_add_del
{
  u32 client_index;
  u32 context;
  bool is_add [default=true];
  /* MACIP ACLs are always input */
  vl_api_interface_index_t sw_if_index;
  u32 acl_index;
  option vat_help = "<intfc> | sw_if_index <if-idx> [add|del] acl <acl-idx>";
};

/** \brief Dump one or all defined MACIP ACLs
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param acl_index - MACIP ACL index or ~0 to dump all MACIP ACLs
*/

define macip_acl_dump
{
  u32 client_index;
  u32 context;
  u32 acl_index; /* ~0 for all ACLs */
  option vat_help = "[<acl-idx>]";
};

/** \brief Details about one MACIP ACL
    @param context - returned sender context, to match reply w/ request
    @param acl_index - index of this MACIP ACL
    @param tag - descriptive tag which was supplied during the creation
    @param count - length of the vector of MACIP ACL rules
    @param r - rules comprising this MACIP ACL
*/

manual_endian manual_print define macip_acl_details
{
  u32 context;
  u32 acl_index;
  string tag[64];
  u32 count;
  vl_api_macip_acl_rule_t r[count];
};

/** \brief Get the vector of MACIP ACL IDs applied to the interfaces
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
*/

define macip_acl_interface_get
{
  u32 client_index;
  u32 context;
};

/** \brief Reply with the vector of MACIP ACLs by sw_if_index
    @param context - returned sender context, to match reply w/ request
    @param count - total number of elements in the vector
    @param acls - the vector of active MACIP ACL indices per sw_if_index
*/

define macip_acl_interface_get_reply
{
  u32 context;
  u32 count;
  u32 acls[count];
};

/** \brief Dump the list(s) of MACIP ACLs applied to specific or all interfaces
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - interface to dump the MACIP ACL list for
*/

define macip_acl_interface_list_dump
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index; /* ~0 for all interfaces */
};

/** \brief Details about a single MACIP ACL contents
    @param context - returned sender context, to match reply w/ request
    @param sw_if_index - interface for which the list of MACIP ACLs is applied
    @param count - total length of acl indices vector
    @param acls - the vector of MACIP ACL indices
*/

define macip_acl_interface_list_details
{
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u8 count;
  u32 acls[count];
};

/** \brief Set the ethertype whitelists on an interface. Takes effect when applying ACLs on the interface, so must be given prior.
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - the interface to alter the list of ACLs on
    @param count - total number of whitelisted ethertypes in the vector
    @param n_input - this many first elements correspond to input whitelisted ethertypes, the rest - output
    @param whitelist - vector of whitelisted ethertypes
*/

autoreply manual_print define acl_interface_set_etype_whitelist
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u8 count; /* Total number of ethertypes in the whitelist */
  u8 n_input; /* first n_input ethertypes are input, the rest - output */
  u16 whitelist[count];
  option vat_help = "<intfc> | sw_if_index <if-idx> input [ethertype list] output [ethertype list]";
};

/** \brief Dump the list(s) of Ethertype whitelists applied to specific or all interfaces
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - interface to dump the ethertype whitelist for
*/

define acl_interface_etype_whitelist_dump
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index; /* ~0 for all interfaces */
  option vat_help = "[<intfc> | sw_if_index <if-idx>]";
};

/** \brief Details about ethertype whitelist on a single interface
    @param context - returned sender context, to match reply w/ request
    @param sw_if_index - interface for which the list of MACIP ACLs is applied
    @param count - total number of whitelisted ethertypes in the vector
    @param n_input - this many first elements correspond to input whitelisted ethertypes, the rest - output
    @param whitelist - vector of whitelisted ethertypes
*/

define acl_interface_etype_whitelist_details
{
  u32 context;
  vl_api_interface_index_t sw_if_index;
  u8 count;
  u8 n_input; /* first n_input ethertypes are input, the rest - output */
  u16 whitelist[count];
};

/** \brief Enable or disable incrementing ACL counters in stats segment by interface processing
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param enable - whether to enable or disable incrementing the counters
*/

autoreply define acl_stats_intf_counters_enable
{
  u32 client_index;
  u32 context;
  bool enable;
  option vat_help = "[disable]";
};