[spp] [PATCH v2 1/9] docs: overview

[Itsuro ODA <oda@valinux.co.jp>]

From: Itsuro Oda <oda at valinux.co.jp>

Signed-off-by: Itsuro Oda <oda@valinux.co.jp>
---
 docs/guides/spp-ctl/overview.rst | 102 +++++++++++++++++++++++++++++++
 1 file changed, 102 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..847b9dc
--- /dev/null
+++ b/docs/guides/spp-ctl/overview.rst
@@ -0,0 +1,102 @@
+====================================
+spp-ctl: SPP controller with Web API
+====================================
+
+Overview
+========
+
+spp-ctl is a SPP controller with a REST like web API.
+
+spp-ctl maintains the connections from the SPP processes and at the same
+time exposes the API for the user to request for the SPP processes.
+
+Background and motivation
+-------------------------
+
+Current CLI (spp.py/spp_vf.py) can be used by intaractive only.
+Therefore, spp-agent, a component of networking-spp which make SPP
+available on OpenStack environment, implements SPP controller in
+itself. (see. https://github.com/openstack/networking-spp )
+
+Either CLI or spp-agent, there is a problem that other people can not
+request to SPP processes while using. spp-ctl is invented to solve this
+problem.
+
+Both CLI and spp-agent can be used spp-ctl to request SPP processes
+instead of owning contoroller itself. In that case, multiple people
+can request to SPP processes at the same time.
+Note that spp-agent has a plan to change to use spp-ctl.
+It is also available not using CLI but requesting spp-ctl directly.
+
+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 (it is simple and well known) as a web framework
+and eventlet for parallel processing. spp-ctl can process multiple APIs
+at the same time, however, requests for per SPP process are serialized
+internally.
+
+
+Setup
+=====
+
+spp-ctl is a simple program written in python3. Installation of related
+packages is as follows (assume ubuntu).
+
+::
+
+  $ sudo apt update
+  $ sudo apt install python3
+  $ sudo apt install python3-pip
+  $ sudo pip3 install -r requirements.txt
+
+Usage
+-----
+
+::
+
+  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
+-------------
+
+Although spp-ctl runs as a daemon process normaly, it assumes to the
+use of systemd and does not daemonize itself.
+
+The service file for systemd is simple as shown below::
+
+  [Unit]
+  Description = SPP Controller
+
+  [Service]
+  ExecStart = {SPP install path}/spp_ctl/spp-ctl -p 5555 -s 6666 -a 7777
+  User = root
+
+API Usage
+=========
+
+For API details, see API-reference_.
+
+.. _API-reference: ./api-reference.rst
+
+Since spp-ctl provides the web API, for example, you can use curl to execute
+requests as follows::
+
+  $ curl http://localhost:7777/v1/processes
+  [{"type": "primary"}, {"client-id": 1, "type": "vf"}, {"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"}'
+  $
+
-- 
2.17.0
-- 
Itsuro ODA <oda@valinux.co.jp>