summaryrefslogtreecommitdiffstats
path: root/docs/cli-reference/gettingstarted/index.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/cli-reference/gettingstarted/index.rst')
-rw-r--r--docs/cli-reference/gettingstarted/index.rst126
1 files changed, 126 insertions, 0 deletions
diff --git a/docs/cli-reference/gettingstarted/index.rst b/docs/cli-reference/gettingstarted/index.rst
new file mode 100644
index 00000000000..6528725de45
--- /dev/null
+++ b/docs/cli-reference/gettingstarted/index.rst
@@ -0,0 +1,126 @@
+.. _cli_getting_started:
+
+Getting Started with the debug CLI
+==================================
+
+The VPP network stack comes equipped with a set of commands that are useful
+for debugging.
+
+The easiest way to access the CLI (with proper permissions) is to use the
+vppctl command:
+
+.. code-block:: console
+
+ sudo vppctl <cli-command>
+
+
+The CLI parser matches static keyword strings, eventually invoking an action
+function. Unambiguous partial keyword matching always occurs. The action
+functions consume input until satisfied or until they fail. This model makes
+for easy coding, but does not guarantee useful "help" output. It's up to the
+CLI command writer to add useful help strings.
+
+You can find the source code of CLI commands by searching for instances of the
+``VLIB_CLI_COMMAND`` macro in the code source files.
+
+Please help maintain and improve this document to make and keep these commands
+clear and useful!
+
+.. _debug_telnet_cli:
+
+Debug and Telnet CLI
+--------------------
+
+The debug CLI is enabled with the unix interactive parameter or startup
+configuration option. This causes VPP to start without daemonizing and
+presents a command line interface on the terminal where it is run.
+
+The Telnet CLI is enabled with the ``cli-listen localhost:5002`` option which
+will cause VPP to listen for TCP connections on the localhost address port
+``5002``. A Telnet client can then connect to this port (for example, ``telnet
+localhost 5002``) and will receive a command line prompt.
+
+This configuration will enable both mechanisms:
+
+.. code-block:: console
+
+ unix {
+ interactive
+ cli-listen localhost:5002
+ }
+
+
+The debug CLI can operate in line mode, which may be useful when running
+inside an IDE like Emacs. This is enabled with the option
+``unix cli-line-mode``. Several other options exist that alter how this
+CLI works, see the @ref syscfg section for details.
+
+The CLI starts with a banner graphic (which can be disabled) and a prompt. The
+prompt will typically read ``vpp`` for a release version of VPP and ``DBGvpp#``
+for a development version with debugging enabled, for example:
+
+.. code-block:: console
+
+ _______ _ _ _____ ___
+ __/ __/ _ \ (_)__ | | / / _ \/ _ \
+ _/ _// // / / / _ \ | |/ / ___/ ___/
+ /_/ /____(_)_/\___/ |___/_/ /_/
+
+ vpp#
+
+
+
+versus:
+
+.. code-block:: console
+
+ _______ _ _ _____ ___
+ __/ __/ _ \ (_)__ | | / / _ \/ _ \
+ _/ _// // / / / _ \ | |/ / ___/ ___/
+ /_/ /____(_)_/\___/ |___/_/ /_/
+
+ DBGvpp#
+
+
+This prompt can be configured with the ``unix cli-prompt`` setting and the
+banner is disabled with ``unix cli-no-banner``.
+
+.. _cli_features:
+
+CLI features
+------------
+
+The CLI has several editing features that make it easy to use.
+
+- Cursor keys ``left/right`` will move the cursor within a command line;
+ typing will insert at the cursor; erase will erase at the cursor.
+
+- ``Ctrl-left/right`` will search for the start of the next word to
+ the left or right.
+- ``Home/end`` will jump the cursor to the start and end of the line.
+- Cursor keys up/down and ``^P/^N`` iterate through the command history
+ buffer. Lines from the history buffer may be edited. New commands
+ are added to the end of the buffer when executed; though
+ duplicates of the previous command are not added.
+- ``^U`` erases the line contents from the left of the cursor to the
+ start.
+- ``^K`` erases the contents from the cursor to the end.
+- ``^S/^R`` will search the command history forwards or in reverse for
+ a command; start typing for matches to auto complete.
+- ``^L`` will clear the screen (if supported by the terminal) and repaint
+ the prompt and any current line. The cursor position is also
+ retained.
+- The CLI can be closed with the quit command. Alternatively, ``^D`` on
+ an empty input line will also close the session. Closing the debug
+ session will also shutdown VPP.
+
+Output that exceeds the length of a terminal page will be buffered, up to a
+limit.
+
+- ``Space`` or ``page-down`` displays the next page.
+- ``Enter`` or ``down-arrow`` displays the next line.
+- ``Page-up`` goes back a page.
+- ``Up-arrow`` goes up a line.
+- ``Home/end`` jump to the start/end of the buffered output.
+- The key ``q`` quits the pager. ``Space`` and ``enter`` will also quit the
+ pager if the end of the buffer has been reached. \ No newline at end of file