From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from valinux.co.jp (vagw.valinux.co.jp [210.128.90.14]) by dpdk.org (Postfix) with ESMTP id 1BDCE5B30 for ; Fri, 5 Oct 2018 05:58:00 +0200 (CEST) Received: by valinux.co.jp (Postfix, from userid 1000) id 77AD1240C79; Fri, 5 Oct 2018 12:57:57 +0900 (JST) From: oda@valinux.co.jp To: spp@dpdk.org, ferruh.yigit@intel.com, ogawa.yasufumi@lab.ntt.co.jp Date: Fri, 5 Oct 2018 12:57:44 +0900 Message-Id: <20181005035757.23122-2-oda@valinux.co.jp> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20181005035757.23122-1-oda@valinux.co.jp> References: <20180913082544.2D36.277DD91C@valinux.co.jp> <20181005035757.23122-1-oda@valinux.co.jp> Subject: [spp] [PATCH v4 01/14] docs: add overview of spp-ctl X-BeenThere: spp@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Soft Patch Panel List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 05 Oct 2018 03:58:01 -0000 From: Itsuro Oda Add overview section of spp-ctl. Signed-off-by: Itsuro Oda --- docs/guides/spp-ctl/overview.rst | 119 +++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 docs/guides/spp-ctl/overview.rst diff --git a/docs/guides/spp-ctl/overview.rst b/docs/guides/spp-ctl/overview.rst new file mode 100644 index 0000000..4c7181c --- /dev/null +++ b/docs/guides/spp-ctl/overview.rst @@ -0,0 +1,119 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Nippon Telegraph and Telephone Corporation + +.. _spp_ctl_overview: + +spp-ctl +======= + +Overview +-------- + +``spp-ctl`` is an alternative SPP controller which provides a REST-like +APIs. + +It maintains connections between SPP processes for managing them +via the REST-like APIs for users or other processes. + +Background and Motivation +------------------------- + +``spp-ctl`` is designed for supporting to manage SPP from several +controllers. + +There are some usecases where SPP is managed from other +process without user inputs. +For example, you need a intermediate process if you think of using SPP +from a framework, such as OpenStack. +`networking-spp +`_ +is a Neutron ML2 plugin for SPP and `spp-agent` works as a +SPP controller. + +It is a problem to prepare several controllers for each of usages for +CLI, OpenStack or others because it would be hard to maintain for +updates. + +Spp-ctl is designed to solve the problem of several controllers with +application-independent REST APIs. +You can manage SPP by requesting via this APIs. + +Architecture +------------ + +The design goal of spp-ctl is to be as simple as possible. +It is stateless. +Basically, spp-ctl only converts API requests into commands of SPP +processes and throws request, thouth it does syntax and lexical check +for API requests. + +``spp-ctl`` adopts +`bottle +`_ +which is simple and well known as a web framework and +`eventlet +`_ +for parallel processing. +``spp-ctl`` accepts multiple requests at the same time and serializes them +internally. + + +Setup +===== + +You are required to install Python3 and packages described in +``requirements.txt`` via ``pip3`` for launching ``spp-ctl``. +You might need to run ``pip3`` with ``sudo``. + +.. code-block:: console + + $ sudo apt update + $ sudo apt install python3 + $ sudo apt install python3-pip + $ pip3 install -r requirements.txt + +Usage +----- + +.. code-block:: console + + usage: spp-ctl [-p PRI_PORT] [-s SEC_PORT] [-a API_PORT] + + optional arguments: + -p PRI_PORT primary port. default is 5555. + -s SEC_PORT secondary port. default is 6666. + -a API_PORT web api port. default is 7777. + +Using systemd +------------- + +`spp-ctl` is assumed to be launched as a daemon process, or managed +by `systemd`. +Here is a simple example of service file for systemd. + +:: + + [Unit] + Description = SPP Controller + + [Service] + ExecStart = /usr/bin/python3 /path/to/spp/src/spp-ctl/spp-ctl + User = root + + +REST APIs +========= + +You can try to call ``spp-ctl`` APIs with ``curl`` command as following. + +.. code-block:: console + + $ curl http://localhost:7777/v1/processes + [{"type": "primary"}, ..., {"client-id": 2, "type": "vf"}] + $ curl http://localhost:7777/v1/vfs/1 + ... snip + $ curl -X POST http://localhost:7777/v1/vfs/1/components \ + -d '{"core": 2, "name": "forward_0_tx", "type": "forward"}' + +For more details, see +:ref:`API Reference`. -- 2.17.1