summaryrefslogtreecommitdiffstats
path: root/docs/configuration/config_getting_started.rst
diff options
context:
space:
mode:
authorNathan Skrzypczak <nathan.skrzypczak@gmail.com>2021-08-19 11:38:06 +0200
committerDave Wallace <dwallacelf@gmail.com>2021-10-13 23:22:32 +0000
commit9ad39c026c8a3c945a7003c4aa4f5cb1d4c80160 (patch)
tree3cca19635417e28ae381d67ae31c75df2925032d /docs/configuration/config_getting_started.rst
parentf47122e07e1ecd0151902a3cabe46c60a99bee8e (diff)
docs: better docs, mv doxygen to sphinx
This patch refactors the VPP sphinx docs in order to make it easier to consume for external readers as well as VPP developers. It also makes sphinx the single source of documentation, which simplifies maintenance and operation. Most important updates are: - reformat the existing documentation as rst - split RELEASE.md and move it into separate rst files - remove section 'events' - remove section 'archive' - remove section 'related projects' - remove section 'feature by release' - remove section 'Various links' - make (Configuration reference, CLI docs, developer docs) top level items in the list - move 'Use Cases' as part of 'About VPP' - move 'Troubleshooting' as part of 'Getting Started' - move test framework docs into 'Developer Documentation' - add a 'Contributing' section for gerrit, docs and other contributer related infos - deprecate doxygen and test-docs targets - redirect the "make doxygen" target to "make docs" Type: refactor Change-Id: I552a5645d5b7964d547f99b1336e2ac24e7c209f Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com> Signed-off-by: Andrew Yourtchenko <ayourtch@gmail.com>
Diffstat (limited to 'docs/configuration/config_getting_started.rst')
-rw-r--r--docs/configuration/config_getting_started.rst84
1 files changed, 84 insertions, 0 deletions
diff --git a/docs/configuration/config_getting_started.rst b/docs/configuration/config_getting_started.rst
new file mode 100644
index 00000000000..9321ce6a6c8
--- /dev/null
+++ b/docs/configuration/config_getting_started.rst
@@ -0,0 +1,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 \ No newline at end of file