From 06dcd45ff81e06bc8cf40ed487c0b2652d346a5a Mon Sep 17 00:00:00 2001 From: John DeNisco Date: Thu, 26 Jul 2018 12:45:10 -0400 Subject: Initial commit of Sphinx docs Change-Id: I9fca8fb98502dffc2555f9de7f507b6f006e0e77 Signed-off-by: John DeNisco --- docs/gettingstarted/users/installing/centos.rst | 247 ++++++++++++++++++++++ docs/gettingstarted/users/installing/index.rst | 47 ++++ docs/gettingstarted/users/installing/opensuse.rst | 51 +++++ docs/gettingstarted/users/installing/packages.rst | 83 ++++++++ docs/gettingstarted/users/installing/ubuntu.rst | 81 +++++++ 5 files changed, 509 insertions(+) create mode 100644 docs/gettingstarted/users/installing/centos.rst create mode 100644 docs/gettingstarted/users/installing/index.rst create mode 100644 docs/gettingstarted/users/installing/opensuse.rst create mode 100644 docs/gettingstarted/users/installing/packages.rst create mode 100644 docs/gettingstarted/users/installing/ubuntu.rst (limited to 'docs/gettingstarted/users/installing') diff --git a/docs/gettingstarted/users/installing/centos.rst b/docs/gettingstarted/users/installing/centos.rst new file mode 100644 index 00000000000..bb69eb9e797 --- /dev/null +++ b/docs/gettingstarted/users/installing/centos.rst @@ -0,0 +1,247 @@ +.. _centos: + +.. toctree:: + +Setup the fd.io Repository - Centos 7 +===================================== + +Update the OS +------------- + +It is probably a good idea to update and upgrade the OS before starting: + +.. code-block:: console + + $ sudo yum update + + +Point to the Repository +----------------------- + +For CentOS based systems, there are two respositories to pull VPP binaries +from. + +* CentOS NFV SIG Repository +* Nexus Repository + + +CentOS NFV SIG Repository +^^^^^^^^^^^^^^^^^^^^^^^^^ + +VPP is not in the official CentOS 7 distro. However, CentOS has Special +Interest Groups (SIG), which are smaller groups within the CentOS community that +focus on a small set of issues. The CentOS NFV (Network Function Virtualization) +SIG was created to provide a CentOS-based stack that will serve as a platform +for the deployment and testing of virtual network functions (VNFs). VPP has been +included in this SIG. + +To install released packages from the CentOS NFV SIG Repository on an updated +Centos 7 system, first, install the CentOS NFV SIG FIDO repo file: + +.. code-block:: console + + $ sudo yum install centos-release-fdio + +then **'Install VPP RPMs'**, as described below. + +This will install the latest VPP version from the repository. To install an +older version, once the CentOS NFV SIG FDIO repo file has been installed, list +the stored versions: + +.. code-block:: console + + $ sudo yum --showduplicates list vpp* | expand + Loaded plugins: fastestmirror + Loading mirror speeds from cached hostfile + * base: repos-va.psychz.net + * epel: download-ib01.fedoraproject.org + * extras: mirror.siena.edu + * updates: repo1.ash.innoscale.net + Available Packages + vpp.x86_64 17.10-1 centos-fdio + vpp.x86_64 18.01.1-1 centos-fdio + vpp.x86_64 18.01.2-1 centos-fdio + vpp.x86_64 18.04-1 centos-fdio + vpp-api-java.x86_64 17.10-1 centos-fdio + vpp-api-java.x86_64 18.01.1-1 centos-fdio + vpp-api-java.x86_64 18.01.2-1 centos-fdio + vpp-api-java.x86_64 18.04-1 centos-fdio + vpp-api-lua.x86_64 17.10-1 centos-fdio + vpp-api-lua.x86_64 18.01.1-1 centos-fdio + vpp-api-lua.x86_64 18.01.2-1 centos-fdio + vpp-api-lua.x86_64 18.04-1 centos-fdio + vpp-api-python.x86_64 17.10-1 centos-fdio + vpp-api-python.x86_64 18.01.1-1 centos-fdio + vpp-api-python.x86_64 18.01.2-1 centos-fdio + vpp-api-python.x86_64 18.04-1 centos-fdio + vpp-devel.x86_64 17.10-1 centos-fdio + vpp-devel.x86_64 18.01.1-1 centos-fdio + vpp-devel.x86_64 18.01.2-1 centos-fdio + vpp-devel.x86_64 18.04-1 centos-fdio + vpp-lib.x86_64 17.10-1 centos-fdio + vpp-lib.x86_64 18.01.1-1 centos-fdio + vpp-lib.x86_64 18.01.2-1 centos-fdio + vpp-lib.x86_64 18.04-1 centos-fdio + vpp-plugins.x86_64 17.10-1 centos-fdio + vpp-plugins.x86_64 18.01.1-1 centos-fdio + vpp-plugins.x86_64 18.01.2-1 centos-fdio + vpp-plugins.x86_64 18.04-1 centos-fdio + vpp-selinux-policy.x86_64 18.04-1 centos-fdio + +Then install a particular version: + +.. code-block:: console + + $ sudo yum install vpp-17.10-1.x86_64 + + +Nexus Repository +^^^^^^^^^^^^^^^^ + +Build artifacts are also posted to a FD.io Nexus Repository. This includes +official point releases, as well as nightly builds. To use any of these build +artifacts, create a file *'/etc/yum.repos.d/fdio-release.repo'* with the +content that points to the version needed. Below are some common examples of +the content needed: + + +VPP Latest Release +"""""""""""""""""" + +To allow *'yum'* access to the official VPP releases, create the file +*'/etc/yum.repos.d/fdio-release.repo'* with the following content: + +.. code-block:: console + + $ cat /etc/yum.repos.d/fdio-release.repo + [fdio-release] + name=fd.io release branch latest merge + baseurl=https://nexus.fd.io/content/repositories/fd.io.centos7/ + enabled=1 + gpgcheck=0 + +The *'yum install vpp'* command will install the most recent release. To +install older releases, run the following command to get the list of releases +provided: + +.. code-block:: console + + $ sudo yum --showduplicates list vpp* | expand + +Then choose the release to install. See **'CentOS NFV SIG Repository'** for +sample *'yum --showduplicates list'* output and an example of installing a +particular version of the RPMs. + +VPP Stable Branch +""""""""""""""""" + +To allow *yum* access to the build artifacts for a VPP stable branch, create +the file *'/etc/yum.repos.d/fdio-release.repo'* with the following content: + +.. code-block:: console + + $ cat /etc/yum.repos.d/fdio-release.repo + [fdio-stable-1804] + name=fd.io stable/1804 branch latest merge + baseurl=https://nexus.fd.io/content/repositories/fd.io.stable.1804.centos7/ + enabled=1 + gpgcheck=0 + +For other stable branches, replace the *'1804'* from the above content with the +desired release. Examples: 1606, 1609, 1701, 1704, 1707, 1710, 1804, 1807 + +The *'yum install vpp'* command will install the most recent build on the +branch, not the latest offical release. Run the following command to get the +list of images produce by the branch: + +.. code-block:: console + + $ sudo yum --showduplicates list vpp* | expand + +Then choose the image to install. See **'CentOS NFV SIG Repository'** for +sample *'yum --showduplicates list'* output and an example of installing a +particular version of the RPMs. + + +VPP Master Branch +""""""""""""""""" + +To allow *yum* access to the nightly builds from the VPP master branch, create +the file *'/etc/yum.repos.d/fdio-release.repo'* with the following content: + +.. code-block:: console + + $ cat /etc/yum.repos.d/fdio-release.repo + [fdio-master] + name=fd.io master branch latest merge + baseurl=https://nexus.fd.io/content/repositories/fd.io.master.centos7/ + enabled=1 + gpgcheck=0 + +The *'yum install vpp'* command will install the most recent build on the +branch. Run the following command to get the list of images produce by the +branch: + +.. code-block:: console + + $ sudo yum --showduplicates list vpp* | expand + +Then choose the image to install. See **'CentOS NFV SIG Repository'** for +sample *'yum --showduplicates list'* output and an example of installing a +particular version of the RPMs. + + +Install VPP RPMs +================ + +To install the VPP packet engine, run the following: + +.. code-block:: console + + $ sudo yum install vpp + +The **'vpp'** RPM depend on the **'vpp-lib'** and **'vpp-selinux-policy'** +RPMs, so they will be installed as well. + +.. note:: + + The **'vpp-selinux-policy'** will not enable SELinux on the system. It + will install a Custom VPP SELinux policy that will be used if SELinux is + enabled at any time. + +There are additional packages that are optional. These packages can be +combined with the command above and installed all at once, or installed as +needed: + +.. code-block:: console + + $ sudo yum install vpp-plugins vpp-devel vpp-api-python vpp-api-lua vpp-api-java + +Starting VPP +============ + +Once VPP is installed on the system, to run VPP as a systemd service on CentOS, +run: + +.. code-block:: console + + $ sudo systemctl start vpp + +Then to enable VPP to start on system reboot: + +.. code-block:: console + + $ sudo systemctl enable vpp + + +Outside of running VPP as a systemd service, VPP can be started manually or +made to run within GDB for debugging. See :ref:`running` for more details and +ways to tailor VPP to a specific system. + + +Uninstall the VPP RPMs +====================== + +.. code-block:: console + + $ sudo yum autoremove vpp* diff --git a/docs/gettingstarted/users/installing/index.rst b/docs/gettingstarted/users/installing/index.rst new file mode 100644 index 00000000000..7636ec875fd --- /dev/null +++ b/docs/gettingstarted/users/installing/index.rst @@ -0,0 +1,47 @@ +.. _installing: + +.. toctree:: + +Installing VPP from Packages +============================ + +If you are simply using vpp, it can be convenient to install the binaries from +existing packages. This guide will describe how pull, install and run the VPP +packages. + +.. toctree:: + +Package Descriptions +-------------------- +The following is a brief description of the packages to be installed with VPP. + +.. toctree:: + + packages + +Installing VPP Binaries +----------------------- + +Installing on Ubuntu +^^^^^^^^^^^^^^^^^^^^ +The following are instructions on how to install VPP on Ubuntu. + +.. toctree:: + + ubuntu + +Installing on Centos +^^^^^^^^^^^^^^^^^^^^ +The following are instructions on how to install VPP on Centos. + +.. toctree:: + + centos + +Installing on openSUSE +^^^^^^^^^^^^^^^^^^^^^^ +The following are instructions on how to install VPP on openSUSE. + +.. toctree:: + + opensuse diff --git a/docs/gettingstarted/users/installing/opensuse.rst b/docs/gettingstarted/users/installing/opensuse.rst new file mode 100644 index 00000000000..8e91ebd2f45 --- /dev/null +++ b/docs/gettingstarted/users/installing/opensuse.rst @@ -0,0 +1,51 @@ +.. _opensuse: + +.. toctree:: + +Installing +========== +Top install VPP on openSUSE first pick the following release and execute the appropriate commands. + +openSUSE Tumbleweed (rolling release) +------------------------------------- + +.. code-block:: console + + sudo zypper install vpp vpp-plugins + +openSUSE Leap 42.3 +------------------ + +.. code-block:: console + + sudo zypper addrepo --name network https://download.opensuse.org/repositories/network/openSUSE_Leap_42.3/network.repo + sudo zypper install vpp vpp-plugins + +Uninstall +========= + +.. code-block:: console + + sudo zypper remove -u vpp vpp-plugins + +openSUSE Tumbleweed (rolling release) +------------------------------------- + +.. code-block:: console + + sudo zypper remove -u vpp vpp-plugins + +openSUSE Leap 42.3 +------------------ + +.. code-block:: console + + sudo zypper remove -u vpp vpp-plugins + sudo zypper removerepo network + +For More Information +==================== +For more information on VPP with openSUSE, please look at the following post. + +* https://www.suse.com/communities/blog/vector-packet-processing-vpp-opensuse/ + diff --git a/docs/gettingstarted/users/installing/packages.rst b/docs/gettingstarted/users/installing/packages.rst new file mode 100644 index 00000000000..d67ff605d99 --- /dev/null +++ b/docs/gettingstarted/users/installing/packages.rst @@ -0,0 +1,83 @@ +.. _packages: + +Packages +======== + +.. toctree:: + +vpp +--- + +Vector Packet Processing executables. This is the primary package that must be +installed to use VPP. This package contains: + +* vpp - the vector packet engine +* vpp_api_test - vector packet engine API test tool +* vpp_json_test - vector packet engine JSON test tool + +vpp-lib +------- + +Vector Packet Processing runtime libraries. The *'vpp'* package depends on this +package, so it will always be installed. This package contains the VPP shared +libraries, including: + +* vppinfra - Foundation library supporting vectors, hashes, bitmaps, pools, and string formatting. +* svm - vm library +* vlib - vector processing library +* vlib-api - binary API library +* vnet - network stack library + +vpp-plugins +----------- + +Vector Packet Processing plugin modules. + +* acl +* dpdk +* flowprobe +* gtpu +* ixge +* kubeproxy +* l2e +* lb +* memif +* nat +* pppoe +* sixrd +* stn + +vpp-dbg +------- + +Vector Packet Processing debug symbols. + +vpp-dev +------- + +Vector Packet Processing development support. This package contains +development support files for the VPP libraries. + +vpp-api-java +------------ + +JAVA binding for the VPP Binary API. + +vpp-api-python +-------------- + +Python binding for the VPP Binary API. + +vpp-api-lua +----------- + +Lua binding for the VPP Binary API. + +vpp-selinux-policy +------------------ + +This package contains the VPP Custom SELinux Policy. It is only generated for +Fedora and CentOS distros. For those distros, the *'vpp'* package depends on +this package, so it will always be installed. It will not enable SELinux on +the system. It will install a Custom VPP SELinux policy that will be used if +SELinux is enabled at any time. diff --git a/docs/gettingstarted/users/installing/ubuntu.rst b/docs/gettingstarted/users/installing/ubuntu.rst new file mode 100644 index 00000000000..9c082e667b0 --- /dev/null +++ b/docs/gettingstarted/users/installing/ubuntu.rst @@ -0,0 +1,81 @@ +.. _ubuntu: + +.. toctree:: + +Ubuntu 16.04 - Setup the fd.io Repository +========================================= + +From the following choose one of the releases to install. + + +Update the OS +------------- + +It is probably a good idea to update and upgrade the OS before starting + +.. code-block:: console + + apt-get update + + +Point to the Repository +----------------------- + +Create a file **"/etc/apt/sources.list.d/99fd.io.list"** with the contents that point to +the version needed. The contents needed are shown below. + +.. _install_vpp: + +VPP latest Release +^^^^^^^^^^^^^^^^^^ + +Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents: + +.. code-block:: console + + deb [trusted=yes] https://nexus.fd.io/content/repositories/fd.io.ubuntu.xenial.main/ ./ + + +VPP stable/1804 Branch +^^^^^^^^^^^^^^^^^^^^^^ + +Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents: + +.. code-block:: console + + deb [trusted=yes] https://nexus.fd.io/content/repositories/fd.io.stable.1804.ubuntu.xenial.main/ ./ + + +VPP master Branch +^^^^^^^^^^^^^^^^^ + +Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents: + +.. code-block:: console + + deb [trusted=yes] https://nexus.fd.io/content/repositories/fd.io.master.ubuntu.xenial.main/ ./ + + +Install the Mandatory Packages +============================== + +.. code-block:: console + + sudo apt-get update + sudo apt-get install vpp vpp-lib vpp-plugin + + +Install the Optional Packages +============================= + +.. code-block:: console + + sudo apt-get install vpp-dbg vpp-dev vpp-api-java vpp-api-python vpp-api-lua + + +Uninstall the Packages +====================== + +.. code-block:: console + + sudo apt-get remove --purge vpp* -- cgit 1.2.3-korg