From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from tama500.ecl.ntt.co.jp (tama500.ecl.ntt.co.jp [129.60.39.148]) by dpdk.org (Postfix) with ESMTP id 798431B273 for ; Wed, 9 Jan 2019 02:51:45 +0100 (CET) Received: from vc1.ecl.ntt.co.jp (vc1.ecl.ntt.co.jp [129.60.86.153]) by tama500.ecl.ntt.co.jp (8.13.8/8.13.8) with ESMTP id x091piuu016716; Wed, 9 Jan 2019 10:51:44 +0900 Received: from vc1.ecl.ntt.co.jp (localhost [127.0.0.1]) by vc1.ecl.ntt.co.jp (Postfix) with ESMTP id 5B59EEA6F01; Wed, 9 Jan 2019 10:51:44 +0900 (JST) Received: from localhost.localdomain (lobster.nslab.ecl.ntt.co.jp [129.60.13.95]) by vc1.ecl.ntt.co.jp (Postfix) with ESMTP id 35FB6EA736E; Wed, 9 Jan 2019 10:51:44 +0900 (JST) From: ogawa.yasufumi@lab.ntt.co.jp To: ferruh.yigit@intel.com, spp@dpdk.org, ogawa.yasufumi@lab.ntt.co.jp Date: Wed, 9 Jan 2019 10:49:32 +0900 Message-Id: <1546998573-26108-12-git-send-email-ogawa.yasufumi@lab.ntt.co.jp> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1546998573-26108-1-git-send-email-ogawa.yasufumi@lab.ntt.co.jp> References: <1546998573-26108-1-git-send-email-ogawa.yasufumi@lab.ntt.co.jp> X-TM-AS-MML: disable Subject: [spp] [PATCH 11/11] docs: remove spp-ctl section 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: Wed, 09 Jan 2019 01:51:48 -0000 From: Yasufumi Ogawa Move overview, design and setup guide of spp-ctl to each of sections of SPP itself. API reference is only remained to describe not only spp-ctl but all of APIs of SPP which are added in future releases. Signed-off-by: Yasufumi Ogawa --- docs/guides/api_ref/index.rst | 11 + docs/guides/api_ref/spp-ctl.rst | 1723 +++++++++++++++++++++++++++++++++ docs/guides/design/spp_controller.rst | 14 + docs/guides/index.rst | 2 +- docs/guides/setup/getting_started.rst | 21 +- docs/guides/setup/howto_use.rst | 13 + docs/guides/spp-ctl/api-reference.rst | 1714 -------------------------------- docs/guides/spp-ctl/index.rst | 14 - docs/guides/spp-ctl/overview.rst | 87 -- 9 files changed, 1778 insertions(+), 1821 deletions(-) create mode 100644 docs/guides/api_ref/index.rst create mode 100644 docs/guides/api_ref/spp-ctl.rst delete mode 100644 docs/guides/spp-ctl/api-reference.rst delete mode 100644 docs/guides/spp-ctl/index.rst delete mode 100644 docs/guides/spp-ctl/overview.rst diff --git a/docs/guides/api_ref/index.rst b/docs/guides/api_ref/index.rst new file mode 100644 index 0000000..0c3bad3 --- /dev/null +++ b/docs/guides/api_ref/index.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Nippon Telegraph and Telephone Corporation + +API Reference +============= + +.. toctree:: + :maxdepth: 2 + :numbered: + + spp-ctl diff --git a/docs/guides/api_ref/spp-ctl.rst b/docs/guides/api_ref/spp-ctl.rst new file mode 100644 index 0000000..237f91e --- /dev/null +++ b/docs/guides/api_ref/spp-ctl.rst @@ -0,0 +1,1723 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018-2019 Nippon Telegraph and Telephone Corporation + +.. _spp_ctl_rest_api_ref: + +spp-ctl REST API +================ + +Overview +-------- + +``spp-ctl`` provides simple REST like API. It supports http only, not https. + +Request and Response +~~~~~~~~~~~~~~~~~~~~ + +Request body is JSON format. +It is accepted both ``text/plain`` and ``application/json`` +for the content-type header. + +A response of ``GET`` is JSON format and the content-type is +``application/json`` if the request success. + +.. code-block:: console + + $ curl http://127.0.0.1:7777/v1/processes + [{"type": "primary"}, ..., {"client-id": 2, "type": "vf"}] + + $ curl -X POST http://localhost:7777/v1/vfs/1/components \ + -d '{"core": 2, "name": "forward_0_tx", "type": "forward"}' + +If a request is failed, the response is a text which shows error reason +and the content-type is ``text/plain``. + + +Error code +~~~~~~~~~~ + + +``spp-ctl`` does basic syntax and lexical check of a request. + +.. _table_spp_ctl_error_codes: + +.. table:: Error codes in spp-ctl. + + +-------+----------------------------------------------------------------+ + | Error | Description | + | | | + +=======+================================================================+ + | 400 | Syntax or lexical error, or SPP returns error for the request. | + +-------+----------------------------------------------------------------+ + | 404 | URL is not supported, or no SPP process of client-id in a URL. | + +-------+----------------------------------------------------------------+ + | 500 | System error occured in ``spp-ctl``. | + +-------+----------------------------------------------------------------+ + + +API independent of the process type +----------------------------------- + +GET /v1/processes +~~~~~~~~~~~~~~~~~ + +Show the SPP processes connected to the ``spp-ctl``. + +* Normarl response codes: 200 + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X GET -H 'application/json' \ + http://127.0.0.1:7777/v1/processes + +Response +^^^^^^^^ + +An array of process objects. + +process object: + +.. _table_spp_ctl_processes: + +.. table:: Response params of getting processes info. + + +-----------+---------+-----------------------------------------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+=================================================================+ + | type | string | process type. one of ``primary``, ``nfv`` or ``vf``. | + +-----------+---------+-----------------------------------------------------------------+ + | client-id | integer | client id. if type is ``primary`` this member does not exist. | + +-----------+---------+-----------------------------------------------------------------+ + +Response example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + [ + { + "type": "primary" + }, + { + "type": "vf", + "client-id": 1 + }, + { + "type": "nfv", + "client-id": 2 + } + ] + + +API for spp_primary +------------------- + +GET /v1/primary/status +~~~~~~~~~~~~~~~~~~~~~~ + +Show statistical information. + +* Normal response codes: 200 + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X GET -H 'application/json' \ + http://127.0.0.1:7777/v1/primary/status + +Response +^^^^^^^^ + +.. _table_spp_ctl_primary_status: + +.. table:: Response params of primary status. + + +------------+-------+-------------------------------------------+ + | Name | Type | Description | + | | | | + +============+=======+===========================================+ + | phy_ports | array | An array of statistics of physical ports. | + +------------+-------+-------------------------------------------+ + | ring_ports | array | An array of statistics of ring ports. | + +------------+-------+-------------------------------------------+ + +Physical port object. + +.. _table_spp_ctl_primary_status_phy: + +.. table:: Attributes of physical port of primary status. + + +---------+---------+-----------------------------------------------------+ + | Name | Type | Description | + | | | | + +=========+=========+=====================================================+ + | id | integer | Port ID of the physical port. | + +---------+---------+-----------------------------------------------------+ + | rx | integer | The total number of received packets. | + +---------+---------+-----------------------------------------------------+ + | tx | integer | The total number of transferred packets. | + +---------+---------+-----------------------------------------------------+ + | tx_drop | integer | The total number of dropped packets of transferred. | + +---------+---------+-----------------------------------------------------+ + | eth | string | MAC address of the port. | + +---------+---------+-----------------------------------------------------+ + +Ring port object. + +.. _table_spp_ctl_primary_status_ring: + +.. table:: Attributes of ring port of primary status. + + +---------+---------+-----------------------------------------------------+ + | Name | Type | Description | + | | | | + +=========+=========+=====================================================+ + | id | integer | Port ID of the ring port. | + +---------+---------+-----------------------------------------------------+ + | rx | integer | The total number of received packets. | + +---------+---------+-----------------------------------------------------+ + | rx_drop | integer | The total number of dropped packets of received. | + +---------+---------+-----------------------------------------------------+ + | tx | integer | The total number of transferred packets. | + +---------+---------+-----------------------------------------------------+ + | tx_drop | integer | The total number of dropped packets of transferred. | + +---------+---------+-----------------------------------------------------+ + +Response example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "phy_ports": [ + { + "id": 0, + "rx": 0, + "tx": 0, + "tx_drop": 0, + "eth": "56:48:4f:53:54:00" + }, + { + "id": 1, + "rx": 0, + "tx": 0, + "tx_drop": 0, + "eth": "56:48:4f:53:54:01" + } + ], + "ring_ports": [ + { + "id": 0, + "rx": 0, + "rx_drop": 0, + "tx": 0, + "tx_drop": 0 + }, + { + "id": 1, + "rx": 0, + "rx_drop": 0, + "tx": 0, + "tx_drop": 0 + }, + { + "id": 2, + "rx": 0, + "rx_drop": 0, + "tx": 0, + "tx_drop": 0 + }, + { + "id": 3, + "rx": 0, + "rx_drop": 0, + "tx": 0, + "tx_drop": 0 + } + ] + } + + +DELETE /v1/primary/status +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Clear statistical information. + +* Normal response codes: 204 + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X DELETE -H 'application/json' \ + http://127.0.0.1:7777/v1/primary/status + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``DELETE`` request. + +DELETE /v1/primary +~~~~~~~~~~~~~~~~~~ + +Terminate primary process. + +* Normal response codes: 204 + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X DELETE -H 'application/json' \ + http://127.0.0.1:7777/v1/primary + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``DELETE`` request. + + +API for spp_nfv/spp_vm +---------------------- + +GET /v1/nfvs/{client_id} +~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the information of the ``spp_nfv`` or ``spp_vm`` process. + +* Normal response codes: 200 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_nfvs_get: + +.. table:: Request parameter for getting spp_nfv or spp_vm info. + + +-----------+---------+-------------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+=====================================+ + | client_id | integer | client id. | + +-----------+---------+-------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X GET -H 'application/json' \ + http://127.0.0.1:7777/v1/nfvs/1 + +Response +^^^^^^^^ + +.. _table_spp_ctl_spp_nfv_res: + +.. table:: Response params of getting spp_nfv or spp_vm info. + + +-----------+---------+---------------------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+=============================================+ + | client-id | integer | client id. | + +-----------+---------+---------------------------------------------+ + | status | string | ``Running`` or ``Idle``. | + +-----------+---------+---------------------------------------------+ + | ports | array | an array of port ids used by the process. | + +-----------+---------+---------------------------------------------+ + | patches | array | an array of patches. | + +-----------+---------+---------------------------------------------+ + +patch objest + +.. _table_spp_ctl_patch_spp_nfv: + +.. table:: Attributes of patch of spp_nfv or spp_vm. + + +------+--------+----------------------------------------------+ + | Name | Type | Description | + | | | | + +======+========+==============================================+ + | src | string | source port id. | + +------+--------+----------------------------------------------+ + | dst | string | destination port id. | + +------+--------+----------------------------------------------+ + +Response example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "client-id": 1, + "status": "Running", + "ports": [ + "phy:0", "phy:1", "vhost:0", "vhost:1", "ring:0", "ring:1", "ring:2", "ring:3" + ], + "patches": [ + { + "src": "vhost:0", "dst": "ring:0" + }, + { + "src": "ring:1", "dst": "vhost:1" + } + ] + } + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + sec {client_id};status + + +PUT /v1/nfvs/{client_id}/forward +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Start or Stop forwarding. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_nfv_forward_get: + +.. table:: Request params of forward of spp_nfv or spp_vm. + + +-----------+---------+---------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+=================================+ + | client_id | integer | client id. | + +-----------+---------+---------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X PUT -H 'application/json' \ + -d '{"action": "start"}' \ + http://127.0.0.1:7777/v1/nfvs/1/forward + +Request(body) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_nfv_forward_get_body: + +.. table:: Request body params of forward of spp_nfv or spp_vm. + + +--------+--------+-------------------------------------+ + | Name | Type | Description | + | | | | + +========+========+=====================================+ + | action | string | ``start`` or ``stop``. | + +--------+--------+-------------------------------------+ + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``PUT`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +action is ``start`` + +.. code-block:: none + + sec {client_id};forward + +action is ``stop`` + +.. code-block:: none + + sec {client_id};stop + + +PUT /v1/nfvs/{client_id}/ports +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add or Delete port. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_nfv_ports_get: + +.. table:: Request params of ports of spp_nfv or spp_vm. + + +-----------+---------+--------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+================================+ + | client_id | integer | client id. | + +-----------+---------+--------------------------------+ + +Request(body) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_nfv_ports_get_body: + +.. table:: Request body params of ports of spp_nfv or spp_vm. + + +--------+--------+---------------------------------------------------------------+ + | Name | Type | Description | + | | | | + +========+========+===============================================================+ + | action | string | ``add`` or ``del``. | + +--------+--------+---------------------------------------------------------------+ + | port | string | port id. port id is the form {interface_type}:{interface_id}. | + +--------+--------+---------------------------------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X PUT -H 'application/json' \ + -d '{"action": "add", "port": "ring:0"}' \ + http://127.0.0.1:7777/v1/nfvs/1/ports + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``PUT`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + sec {client_id};{action} {interface_type} {interface_id} + + +PUT /v1/nfvs/{client_id}/patches +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add a patch. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_nfv_patches_get: + +.. table:: Request params of patches of spp_nfv or spp_vm. + + +-----------+---------+---------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+=================================+ + | client_id | integer | client id. | + +-----------+---------+---------------------------------+ + +Request(body) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_nfv_ports_patches_body: + +.. table:: Request body params of patches of spp_nfv or spp_vm. + + +------+--------+------------------------------------+ + | Name | Type | Description | + | | | | + +======+========+====================================+ + | src | string | source port id. | + +------+--------+------------------------------------+ + | dst | string | destination port id. | + +------+--------+------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X PUT -H 'application/json' \ + -d '{"src": "ring:0", "dst": "ring:1"}' \ + http://127.0.0.1:7777/v1/nfvs/1/patches + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``PUT`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + sec {client_id};patch {src} {dst} + + +DELETE /v1/nfvs/{client_id}/patches +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Reset patches. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_nfv_del_patches: + +.. table:: Request params of deleting patches of spp_nfv or spp_vm. + + +-----------+---------+---------------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+=======================================+ + | client_id | integer | client id. | + +-----------+---------+---------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X DELETE -H 'application/json' \ + http://127.0.0.1:7777/v1/nfvs/1/patches + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``DELETE`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + sec {client_id};patch reset + + +DELETE /v1/nfvs/{client_id} +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Terminate ``spp_nfv`` or ``spp_vm`` process. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_nfvs_delete: + +.. table:: Request parameter for terminating spp_nfv or spp_vm. + + +-----------+---------+-------------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+=====================================+ + | client_id | integer | client id. | + +-----------+---------+-------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X DELETE -H 'application/json' \ + http://127.0.0.1:7777/v1/nfvs/1 + +Response example +^^^^^^^^^^^^^^^^ + +There is no body content for the response of a successful ``DELETE`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + sec {client_id}; exit + + +API for spp_vf +-------------- + +GET /v1/vfs/{client_id} +~~~~~~~~~~~~~~~~~~~~~~~ + +Get the information of the ``spp_vf`` process. + +* Normal response codes: 200 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_vfs_get: + +.. table:: Request parameter for getting spp_vf. + + +-----------+---------+--------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+==========================+ + | client_id | integer | client id. | + +-----------+---------+--------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X GET -H 'application/json' \ + http://127.0.0.1:7777/v1/vfs/1 + +Response +^^^^^^^^ + +.. _table_spp_ctl_spp_vf_res: + +.. table:: Response params of getting spp_vf. + + +------------------+---------+-----------------------------------------------+ + | Name | Type | Description | + | | | | + +==================+=========+===============================================+ + | client-id | integer | client id. | + +------------------+---------+-----------------------------------------------+ + | ports | array | an array of port ids used by the process. | + +------------------+---------+-----------------------------------------------+ + | components | array | an array of component objects in the process. | + +------------------+---------+-----------------------------------------------+ + | classifier_table | array | an array of classifier tables in the process. | + +------------------+---------+-----------------------------------------------+ + +component object: + +.. _table_spp_ctl_spp_vf_res_comp: + +.. table:: Component objects of getting spp_vf. + + +---------+---------+---------------------------------------------------------------------+ + | Name | Type | Description | + | | | | + +=========+=========+=====================================================================+ + | core | integer | core id running on the component | + +---------+---------+---------------------------------------------------------------------+ + | name | string | an array of port ids used by the process. | + +---------+---------+---------------------------------------------------------------------+ + | type | string | an array of component objects in the process. | + +---------+---------+---------------------------------------------------------------------+ + | rx_port | array | an array of port objects connected to the rx side of the component. | + +---------+---------+---------------------------------------------------------------------+ + | tx_port | array | an array of port objects connected to the tx side of the component. | + +---------+---------+---------------------------------------------------------------------+ + +port object: + +.. _table_spp_ctl_spp_vf_res_port: + +.. table:: Port objects of getting spp_vf. + + +---------+---------+---------------------------------------------------------------+ + | Name | Type | Description | + | | | | + +=========+=========+===============================================================+ + | port | string | port id. port id is the form {interface_type}:{interface_id}. | + +---------+---------+---------------------------------------------------------------+ + | vlan | object | vlan operation which is applied to the port. | + +---------+---------+---------------------------------------------------------------+ + +vlan object: + +.. _table_spp_ctl_spp_vf_res_vlan: + +.. table:: Vlan objects of getting spp_vf. + + +-----------+---------+-------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+===============================+ + | operation | string | ``add``, ``del`` or ``none``. | + +-----------+---------+-------------------------------+ + | id | integer | vlan id. | + +-----------+---------+-------------------------------+ + | pcp | integer | vlan pcp. | + +-----------+---------+-------------------------------+ + +classifier table: + +.. _table_spp_ctl_spp_vf_res_cls: + +.. table:: Vlan objects of getting spp_vf. + + +-----------+--------+------------------------------------------------------------+ + | Name | Type | Description | + | | | | + +===========+========+============================================================+ + | type | string | ``mac`` or ``vlan``. | + +-----------+--------+------------------------------------------------------------+ + | value | string | mac_address for ``mac``, vlan_id/mac_address for ``vlan``. | + +-----------+--------+------------------------------------------------------------+ + | port | string | port id applied to classify. | + +-----------+--------+------------------------------------------------------------+ + +Response example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "client-id": 1, + "ports": [ + "phy:0", "phy:1", "vhost:0", "vhost:1", "ring:0", "ring:1", "ring:2", "ring:3" + ], + "components": [ + { + "core": 2, + "name": "forward_0_tx", + "type": "forward", + "rx_port": [ + { + "port": "ring:0", + "vlan": { "operation": "none", "id": 0, "pcp": 0 } + } + ], + "tx_port": [ + { + "port": "vhost:0", + "vlan": { "operation": "none", "id": 0, "pcp": 0 } + } + ] + }, + { + "core": 3, + "type": "unuse" + }, + { + "core": 4, + "type": "unuse" + }, + { + "core": 5, + "name": "forward_1_rx", + "type": "forward", + "rx_port": [ + { + "port": "vhost:1", + "vlan": { "operation": "none", "id": 0, "pcp": 0 } + } + ], + "tx_port": [ + { + "port": "ring:3", + "vlan": { "operation": "none", "id": 0, "pcp": 0 } + } + ] + }, + { + "core": 6, + "name": "classifier", + "type": "classifier_mac", + "rx_port": [ + { + "port": "phy:0", + "vlan": { "operation": "none", "id": 0, "pcp": 0 } + } + ], + "tx_port": [ + { + "port": "ring:0", + "vlan": { "operation": "none", "id": 0, "pcp": 0 } + }, + { + "port": "ring:2", + "vlan": { "operation": "none", "id": 0, "pcp": 0 } + } + ] + }, + { + "core": 7, + "name": "merger", + "type": "merge", + "rx_port": [ + { + "port": "ring:1", + "vlan": { "operation": "none", "id": 0, "pcp": 0 } + }, + { + "port": "ring:3", + "vlan": { "operation": "none", "id": 0, "pcp": 0 } + } + ], + "tx_port": [ + { + "port": "phy:0", + "vlan": { "operation": "none", "id": 0, "pcp": 0 } + } + ] + }, + ], + "classifier_table": [ + { + "type": "mac", + "value": "FA:16:3E:7D:CC:35", + "port": "ring:0" + } + ] + } + +The component which type is ``unused`` is to indicate unused core. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + sec {client_id};status + + +POST /v1/vfs/{client_id}/components +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Start the component. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_vf_components: + +.. table:: Request params of components of spp_vf. + + +-----------+---------+-------------+ + | Name | Type | Description | + +===========+=========+=============+ + | client_id | integer | client id. | + +-----------+---------+-------------+ + + +Request(body) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_vf_components_res: + +.. table:: Response params of components of spp_vf. + + +-----------+---------+----------------------------------------------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+======================================================================+ + | name | string | component name. must be unique in the process. | + +-----------+---------+----------------------------------------------------------------------+ + | core | integer | core id. | + +-----------+---------+----------------------------------------------------------------------+ + | type | string | component type. one of ``forward``, ``merge`` or ``classifier_mac``. | + +-----------+---------+----------------------------------------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X POST -H 'application/json' \ + -d '{"name": "forwarder1", "core": 12, "type": "forward"}' \ + http://127.0.0.1:7777/v1/vfs/1/components + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``POST`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + sec {client_id};component start {name} {core} {type} + + +DELETE /v1/vfs/{sec id}/components/{name} +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Stop the component. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_vf_del: + +.. table:: Request params of deleting component of spp_vf. + + +-----------+---------+---------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+=================================+ + | client_id | integer | client id. | + +-----------+---------+---------------------------------+ + | name | string | component name. | + +-----------+---------+---------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X DELETE -H 'application/json' \ + http://127.0.0.1:7777/v1/vfs/1/components/forwarder1 + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``POST`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + sec {client_id};component stop {name} + + +PUT /v1/vfs/{client_id}/components/{name}/ports +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add or Delete port to the component. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_vf_comp_port: + +.. table:: Request params for ports of component of spp_vf. + + +-----------+---------+---------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+===========================+ + | client_id | integer | client id. | + +-----------+---------+---------------------------+ + | name | string | component name. | + +-----------+---------+---------------------------+ + +Request(body) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_vf_comp_port_body: + +.. table:: Request body params for ports of component of spp_vf. + + +---------+---------+-----------------------------------------------------------------+ + | Name | Type | Description | + | | | | + +=========+=========+=================================================================+ + | action | string | ``attach`` or ``detach``. | + +---------+---------+-----------------------------------------------------------------+ + | port | string | port id. port id is the form {interface_type}:{interface_id}. | + +---------+---------+-----------------------------------------------------------------+ + | dir | string | ``rx`` or ``tx``. | + +---------+---------+-----------------------------------------------------------------+ + | vlan | object | vlan operation which is applied to the port. it can be omitted. | + +---------+---------+-----------------------------------------------------------------+ + +vlan object: + +.. _table_spp_ctl_spp_vf_comp_port_body_vlan: + +.. table:: Request body params for vlan ports of component of spp_vf. + + +-----------+---------+----------------------------------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+==========================================================+ + | operation | string | ``add``, ``del`` or ``none``. | + +-----------+---------+----------------------------------------------------------+ + | id | integer | vlan id. ignored when operation is ``del`` or ``none``. | + +-----------+---------+----------------------------------------------------------+ + | pcp | integer | vlan pcp. ignored when operation is ``del`` or ``none``. | + +-----------+---------+----------------------------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X PUT -H 'application/json' \ + -d '{"action": "attach", "port": "vhost:1", "dir": "rx", \ + "vlan": {"operation": "add", "id": 677, "pcp": 0}}' \ + http://127.0.0.1:7777/v1/vfs/1/components/forwarder1/ports + +.. code-block:: console + + curl -X PUT -H 'application/json' \ + -d '{"action": "detach", "port": "vhost:0", "dir": "tx"} \ + http://127.0.0.1:7777/v1/vfs/1/components/forwarder1/ports + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``PUT`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +action is ``attach`` + +.. code-block:: none + + sec {client_id};port add {port} {dir} {name} [add_vlantag {id} {pcp} | del_vlantag] + +action is ``detach`` + +.. code-block:: none + + sec {client_id};port del {port} {dir} {name} + + +PUT /v1/vfs/{sec id}/classifier_table +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set or Unset classifier table. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_vf_cls_table: + +.. table:: Request params for classifier_table of spp_vf. + + +-----------+---------+---------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+===========================+ + | client_id | integer | client id. | + +-----------+---------+---------------------------+ + +Request(body) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_vf_cls_table_body: + +.. table:: Request body params for classifier_table of spp_vf. + + +-------------+-----------------+----------------------------------------------------+ + | Name | Type | Description | + | | | | + +=============+=================+====================================================+ + | action | string | ``add`` or ``del``. | + +-------------+-----------------+----------------------------------------------------+ + | type | string | ``mac`` or ``vlan``. | + +-------------+-----------------+----------------------------------------------------+ + | vlan | integer or null | vlan id for ``vlan``. null or omitted for ``mac``. | + +-------------+-----------------+----------------------------------------------------+ + | mac_address | string | mac address. | + +-------------+-----------------+----------------------------------------------------+ + | port | string | port id. | + +-------------+-----------------+----------------------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X PUT -H 'application/json' \ + -d '{"action": "add", "type": "mac", "mac_address": "FA:16:3E:7D:CC:35", \ + "port": "ring:0"}' \ + http://127.0.0.1:7777/v1/vfs/1/classifier_table + +.. code-block:: console + + curl -X PUT -H 'application/json' \ + -d '{"action": "del", "type": "vlan", "vlan": 475, \ + "mac_address": "FA:16:3E:7D:CC:35", "port": "ring:0"}' \ + http://127.0.0.1:7777/v1/vfs/1/classifier_table + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``PUT`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +type is ``mac`` + +.. code-block:: none + + classifier_table {action} mac {mac_address} {port} + +type is ``vlan`` + +.. code-block:: none + + classifier_table {action} vlan {vlan} {mac_address} {port} + + +API for spp_mirror +------------------ + +GET /v1/mirrors/{client_id} +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the information of the ``spp_mirror`` process. + +* Normal response codes: 200 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_mirrors_get: + +.. table:: Request parameter for getting spp_mirror. + + +-----------+---------+--------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+==========================+ + | client_id | integer | client id. | + +-----------+---------+--------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X GET -H 'application/json' \ + http://127.0.0.1:7777/v1/mirrors/1 + +Response +^^^^^^^^ + +.. _table_spp_ctl_spp_mirror_res: + +.. table:: Response params of getting spp_mirror. + + +------------------+---------+-----------------------------------------------+ + | Name | Type | Description | + | | | | + +==================+=========+===============================================+ + | client-id | integer | client id. | + +------------------+---------+-----------------------------------------------+ + | ports | array | an array of port ids used by the process. | + +------------------+---------+-----------------------------------------------+ + | components | array | an array of component objects in the process. | + +------------------+---------+-----------------------------------------------+ + +component object: + +.. _table_spp_ctl_spp_mirror_res_comp: + +.. table:: Component objects of getting spp_mirror. + + +---------+---------+---------------------------------------------------------------------+ + | Name | Type | Description | + | | | | + +=========+=========+=====================================================================+ + | core | integer | core id running on the component | + +---------+---------+---------------------------------------------------------------------+ + | name | string | an array of port ids used by the process. | + +---------+---------+---------------------------------------------------------------------+ + | type | string | an array of component objects in the process. | + +---------+---------+---------------------------------------------------------------------+ + | rx_port | array | an array of port objects connected to the rx side of the component. | + +---------+---------+---------------------------------------------------------------------+ + | tx_port | array | an array of port objects connected to the tx side of the component. | + +---------+---------+---------------------------------------------------------------------+ + +port object: + +.. _table_spp_ctl_spp_mirror_res_port: + +.. table:: Port objects of getting spp_vf. + + +---------+---------+---------------------------------------------------------------+ + | Name | Type | Description | + | | | | + +=========+=========+===============================================================+ + | port | string | port id. port id is the form {interface_type}:{interface_id}. | + +---------+---------+---------------------------------------------------------------+ + +Response example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "client-id": 1, + "ports": [ + "phy:0", "phy:1", "ring:0", "ring:1", "ring:2" + ], + "components": [ + { + "core": 2, + "name": "mirror_0", + "type": "mirror", + "rx_port": [ + { + "port": "ring:0" + } + ], + "tx_port": [ + { + "port": "ring:1" + }, + { + "port": "ring:2" + } + ] + }, + { + "core": 3, + "type": "unuse" + } + ] + } + +The component which type is ``unused`` is to indicate unused core. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + sec {client_id};status + + +POST /v1/mirrors/{client_id}/components +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Start the component. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_mirror_components: + +.. table:: Request params of components of spp_mirror. + + +-----------+---------+-------------+ + | Name | Type | Description | + +===========+=========+=============+ + | client_id | integer | client id. | + +-----------+---------+-------------+ + + +Request(body) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_mirror_components_res: + +.. table:: Response params of components of spp_mirror. + + +-----------+---------+----------------------------------------------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+======================================================================+ + | name | string | component name. must be unique in the process. | + +-----------+---------+----------------------------------------------------------------------+ + | core | integer | core id. | + +-----------+---------+----------------------------------------------------------------------+ + | type | string | component type. only ``mirror`` is available. | + +-----------+---------+----------------------------------------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X POST -H 'application/json' \ + -d '{"name": "mirror_1", "core": 12, "type": "mirror"}' \ + http://127.0.0.1:7777/v1/mirrors/1/components + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``POST`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + sec {client_id};component start {name} {core} {type} + + +DELETE /v1/mirrors/{client_id}/components/{name} +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Stop the component. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_mirror_del: + +.. table:: Request params of deleting component of spp_mirror. + + +-----------+---------+---------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+=================================+ + | client_id | integer | client id. | + +-----------+---------+---------------------------------+ + | name | string | component name. | + +-----------+---------+---------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X DELETE -H 'application/json' \ + http://127.0.0.1:7777/v1/mirrors/1/components/mirror_1 + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``POST`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + sec {client_id};component stop {name} + + +PUT /v1/mirrors/{client_id}/components/{name}/ports +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add or Delete port to the component. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_mirror_comp_port: + +.. table:: Request params for ports of component of spp_mirror. + + +-----------+---------+---------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+===========================+ + | client_id | integer | client id. | + +-----------+---------+---------------------------+ + | name | string | component name. | + +-----------+---------+---------------------------+ + +Request(body) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_mirror_comp_port_body: + +.. table:: Request body params for ports of component of spp_mirror. + + +---------+---------+-----------------------------------------------------------------+ + | Name | Type | Description | + | | | | + +=========+=========+=================================================================+ + | action | string | ``attach`` or ``detach``. | + +---------+---------+-----------------------------------------------------------------+ + | port | string | port id. port id is the form {interface_type}:{interface_id}. | + +---------+---------+-----------------------------------------------------------------+ + | dir | string | ``rx`` or ``tx``. | + +---------+---------+-----------------------------------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X PUT -H 'application/json' \ + -d '{"action": "attach", "port": "ring:1", "dir": "rx"}' \ + http://127.0.0.1:7777/v1/mirrors/1/components/mirror_1/ports + +.. code-block:: console + + curl -X PUT -H 'application/json' \ + -d '{"action": "detach", "port": "ring:0", "dir": "tx"} \ + http://127.0.0.1:7777/v1/mirrors/1/components/mirror_1/ports + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``PUT`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +action is ``attach`` + +.. code-block:: none + + sec {client_id};port add {port} {dir} {name} + +action is ``detach`` + +.. code-block:: none + + sec {client_id};port del {port} {dir} {name} + + +API for spp_pcap +---------------- + +GET /v1/pcaps/{client_id} +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the information of the ``spp_pcap`` process. + +* Normal response codes: 200 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_pcap_get: + +.. table:: Request parameter for getting spp_pcap info. + + +-----------+---------+-------------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+=====================================+ + | client_id | integer | client id. | + +-----------+---------+-------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X GET -H 'application/json' \ + http://127.0.0.1:7777/v1/pcaps/1 + +Response +^^^^^^^^ + +.. _table_spp_ctl_spp_pcap_res: + +.. table:: Response params of getting spp_pcap. + + +------------------+---------+-----------------------------------------------+ + | Name | Type | Description | + | | | | + +==================+=========+===============================================+ + | client-id | integer | client id. | + +------------------+---------+-----------------------------------------------+ + | status | string | status of the process. "running" or "idle". | + +------------------+---------+-----------------------------------------------+ + | core | array | an array of core objects in the process. | + +------------------+---------+-----------------------------------------------+ + +core object: + +.. _table_spp_ctl_spp_pcap_res_core: + +.. table:: Core objects of getting spp_pcap. + + +----------+---------+----------------------------------------------------------------------+ + | Name | Type | Description | + | | | | + +==========+=========+======================================================================+ + | core | integer | core id | + +----------+---------+----------------------------------------------------------------------+ + | role | string | role of the task running on the core. "receive" or "write". | + +----------+---------+----------------------------------------------------------------------+ + | rx_port | array | an array of port object for caputure. This member exists if role is | + | | | "recieve". Note that there is only a port object in the array. | + +----------+---------+----------------------------------------------------------------------+ + | filename | string | a path name of output file. This member exists if role is "write". | + +----------+---------+----------------------------------------------------------------------+ + +Note that there is only a port object in the array + +port object: + +.. _table_spp_ctl_spp_pcap_res_port: + +.. table:: Port objects of getting spp_pcap. + + +---------+---------+---------------------------------------------------------------+ + | Name | Type | Description | + | | | | + +=========+=========+===============================================================+ + | port | string | port id. port id is the form {interface_type}:{interface_id}. | + +---------+---------+---------------------------------------------------------------+ + +Response example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "client-id": 1, + "status": "running", + "core": [ + { + "core": 2, + "role": "receive", + "rx_port": [ + { + "port": "phy:0" + } + ] + }, + { + "core": 3, + "role": "write", + "filename": "/tmp/spp_pcap.20181108110600.ring0.1.2.pcap" + } + ] + } + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + pcap {client_id}; status + +PUT /v1/pcaps/{client_id}/capture +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Start or Stop capturing. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_pcap_capture: + +.. table:: Request params of capture of spp_pcap. + + +-----------+---------+---------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+=================================+ + | client_id | integer | client id. | + +-----------+---------+---------------------------------+ + +Request(body) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_spp_pcap_capture_body: + +.. table:: Request body params of capture of spp_pcap. + + +--------+--------+-------------------------------------+ + | Name | Type | Description | + | | | | + +========+========+=====================================+ + | action | string | ``start`` or ``stop``. | + +--------+--------+-------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X PUT -H 'application/json' \ + -d '{"action": "start"}' \ + http://127.0.0.1:7777/v1/pcaps/1/capture + +Response +^^^^^^^^ + +There is no body content for the response of a successful ``PUT`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +action is ``start`` + +.. code-block:: none + + pcap {client_id}; start + +action is ``stop`` + +.. code-block:: none + + pcap {client_id}; stop + + +DELETE /v1/pcaps/{client_id} +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Terminate ``spp_pcap`` process. + +* Normal response codes: 204 +* Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + +.. _table_spp_ctl_pcap_delete: + +.. table:: Request parameter for terminating spp_pcap. + + +-----------+---------+-------------------------------------+ + | Name | Type | Description | + | | | | + +===========+=========+=====================================+ + | client_id | integer | client id. | + +-----------+---------+-------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +.. code-block:: console + + curl -X DELETE -H 'application/json' \ + http://127.0.0.1:7777/v1/pcaps/1 + +Response example +^^^^^^^^^^^^^^^^ + +There is no body content for the response of a successful ``DELETE`` request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + pcap {client_id}; exit diff --git a/docs/guides/design/spp_controller.rst b/docs/guides/design/spp_controller.rst index 95a8c5b..208436e 100644 --- a/docs/guides/design/spp_controller.rst +++ b/docs/guides/design/spp_controller.rst @@ -21,11 +21,15 @@ can deploy high-performance NFV services on OpenStack `[1] `_. + spp-ctl ------- ``spp-ctl`` is designed for managing SPP from several controllers via REST-like APIs for users or other applications. +It is implemented to be simple and it is stateless. +Basically, it only converts a request into a command of SPP process and +forward it to the process without any of syntax or lexical checking. There are several usecases where SPP is managed from other process without user inputs. For example, you need a intermediate process if you think of @@ -48,6 +52,16 @@ The default port numbers are ``5555``, ``6666`` and ``7777``. Spp-ctl as a REST API server +``spp-ctl`` accepts multiple requests at the same time and serializes them +by using +`bottle +`_ +which is simple and well known as a web framework and +`eventlet +`_ +for parallel processing. + + SPP CLI ------- diff --git a/docs/guides/index.rst b/docs/guides/index.rst index 8a98755..d230081 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -15,7 +15,7 @@ SPP documentation commands/index tools/index spp_vf/index - spp-ctl/index + api_ref/index This documentation is the latest tagged version, but some of the latest developing features might be not included. diff --git a/docs/guides/setup/getting_started.rst b/docs/guides/setup/getting_started.rst index 896090d..5aaf0ed 100644 --- a/docs/guides/setup/getting_started.rst +++ b/docs/guides/setup/getting_started.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation + Copyright(c) 2017-2019 Nippon Telegraph and Telephone Corporation .. _getting_started: @@ -201,17 +202,27 @@ Clone repository and compile SPP in any directory. $ cd spp $ make # Confirm that $RTE_SDK and $RTE_TARGET are set +It also required to install Python3 and packages for running python scripts +as following. +You might need to run ``pip3`` with ``sudo`` if it is failed. + +.. code-block:: console + + $ sudo apt update + $ sudo apt install python3 + $ sudo apt install python3-pip + $ pip3 install -r requirements.txt + Python 2 or 3 ? ~~~~~~~~~~~~~~~ -You need to install Python for using usertools of DPDK or SPP controller. -DPDK supports both of Python2 and 3. +In SPP, Python3 is required only for running ``spp-ctl``. Other python scripts +are able to be launched both of Python2 and 3. + Howevrer, Python2 will not be maintained after 2020 and SPP is going to update only supporting Python3. - -In SPP, it supports both of Python2 and 3 without spp-ctl currently, but is -going to support only Python3 before the end of 2019. +In SPP, it is planned to support only Python3 before the end of 2019. Binding Network Ports to DPDK diff --git a/docs/guides/setup/howto_use.rst b/docs/guides/setup/howto_use.rst index 8b8fa0b..cbc20af 100644 --- a/docs/guides/setup/howto_use.rst +++ b/docs/guides/setup/howto_use.rst @@ -60,6 +60,19 @@ to be accessed from other processes running on other than local node. # launch with URL http://192.168.1.100:7777 $ python3 src/spp-ctl/spp-ctl -b 192.168.1.100 +``spp-ctl`` is also launched as a daemon process, or managed +by ``systemd``. +Here is a simple example of service file for systemd. + +.. code-block:: none + + [Unit] + Description = SPP Controller + + [Service] + ExecStart = /usr/bin/python3 /path/to/spp/src/spp-ctl/spp-ctl + User = root + All of options can be referred with help option ``-h``. .. code-block:: console diff --git a/docs/guides/spp-ctl/api-reference.rst b/docs/guides/spp-ctl/api-reference.rst deleted file mode 100644 index cb51100..0000000 --- a/docs/guides/spp-ctl/api-reference.rst +++ /dev/null @@ -1,1714 +0,0 @@ -.. SPDX-License-Identifier: BSD-3-Clause - Copyright(c) 2018 Nippon Telegraph and Telephone Corporation - -.. _spp_ctl_api_ref: - -API Reference -============= - -Overview --------- - -``spp-ctl`` provides simple REST like API. It supports http only, not https. - -Request and Response -~~~~~~~~~~~~~~~~~~~~ - -Request body is JSON format. -It is accepted both ``text/plain`` and ``application/json`` -for the content-type header. - -Response of ``GET`` is JSON format and the content-type is -``application/json`` if the request success. - -If a request fails, the response is a text which shows error reason -and the content-type is ``text/plain``. - -Error code -~~~~~~~~~~ - - -``spp-ctl`` does basic syntax and lexical check of a request. - -.. _table_spp_ctl_error_codes: - -.. table:: Error codes in spp-ctl. - - +-------+----------------------------------------------------------------+ - | Error | Description | - | | | - +=======+================================================================+ - | 400 | Syntax or lexical error, or SPP returns error for the request. | - +-------+----------------------------------------------------------------+ - | 404 | URL is not supported, or no SPP process of client-id in a URL. | - +-------+----------------------------------------------------------------+ - | 500 | System error occured in ``spp-ctl``. | - +-------+----------------------------------------------------------------+ - - -API independent of the process type ------------------------------------ - -GET /v1/processes -~~~~~~~~~~~~~~~~~ - -Show the SPP processes connected to the ``spp-ctl``. - -* Normarl response codes: 200 - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X GET -H 'application/json' \ - http://127.0.0.1:7777/v1/processes - -Response -^^^^^^^^ - -An array of process objects. - -process object: - -.. _table_spp_ctl_processes: - -.. table:: Response params of getting processes info. - - +-----------+---------+-----------------------------------------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+=================================================================+ - | type | string | process type. one of ``primary``, ``nfv`` or ``vf``. | - +-----------+---------+-----------------------------------------------------------------+ - | client-id | integer | client id. if type is ``primary`` this member does not exist. | - +-----------+---------+-----------------------------------------------------------------+ - -Response example -^^^^^^^^^^^^^^^^ - -.. code-block:: json - - [ - { - "type": "primary" - }, - { - "type": "vf", - "client-id": 1 - }, - { - "type": "nfv", - "client-id": 2 - } - ] - - -API for spp_primary -------------------- - -GET /v1/primary/status -~~~~~~~~~~~~~~~~~~~~~~ - -Show statistical information. - -* Normal response codes: 200 - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X GET -H 'application/json' \ - http://127.0.0.1:7777/v1/primary/status - -Response -^^^^^^^^ - -.. _table_spp_ctl_primary_status: - -.. table:: Response params of primary status. - - +------------+-------+-------------------------------------------+ - | Name | Type | Description | - | | | | - +============+=======+===========================================+ - | phy_ports | array | An array of statistics of physical ports. | - +------------+-------+-------------------------------------------+ - | ring_ports | array | An array of statistics of ring ports. | - +------------+-------+-------------------------------------------+ - -Physical port object. - -.. _table_spp_ctl_primary_status_phy: - -.. table:: Attributes of physical port of primary status. - - +---------+---------+-----------------------------------------------------+ - | Name | Type | Description | - | | | | - +=========+=========+=====================================================+ - | id | integer | Port ID of the physical port. | - +---------+---------+-----------------------------------------------------+ - | rx | integer | The total number of received packets. | - +---------+---------+-----------------------------------------------------+ - | tx | integer | The total number of transferred packets. | - +---------+---------+-----------------------------------------------------+ - | tx_drop | integer | The total number of dropped packets of transferred. | - +---------+---------+-----------------------------------------------------+ - | eth | string | MAC address of the port. | - +---------+---------+-----------------------------------------------------+ - -Ring port object. - -.. _table_spp_ctl_primary_status_ring: - -.. table:: Attributes of ring port of primary status. - - +---------+---------+-----------------------------------------------------+ - | Name | Type | Description | - | | | | - +=========+=========+=====================================================+ - | id | integer | Port ID of the ring port. | - +---------+---------+-----------------------------------------------------+ - | rx | integer | The total number of received packets. | - +---------+---------+-----------------------------------------------------+ - | rx_drop | integer | The total number of dropped packets of received. | - +---------+---------+-----------------------------------------------------+ - | tx | integer | The total number of transferred packets. | - +---------+---------+-----------------------------------------------------+ - | tx_drop | integer | The total number of dropped packets of transferred. | - +---------+---------+-----------------------------------------------------+ - -Response example -^^^^^^^^^^^^^^^^ - -.. code-block:: json - - { - "phy_ports": [ - { - "id": 0, - "rx": 0, - "tx": 0, - "tx_drop": 0, - "eth": "56:48:4f:53:54:00" - }, - { - "id": 1, - "rx": 0, - "tx": 0, - "tx_drop": 0, - "eth": "56:48:4f:53:54:01" - } - ], - "ring_ports": [ - { - "id": 0, - "rx": 0, - "rx_drop": 0, - "tx": 0, - "tx_drop": 0 - }, - { - "id": 1, - "rx": 0, - "rx_drop": 0, - "tx": 0, - "tx_drop": 0 - }, - { - "id": 2, - "rx": 0, - "rx_drop": 0, - "tx": 0, - "tx_drop": 0 - }, - { - "id": 3, - "rx": 0, - "rx_drop": 0, - "tx": 0, - "tx_drop": 0 - } - ] - } - - -DELETE /v1/primary/status -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Clear statistical information. - -* Normal response codes: 204 - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X DELETE -H 'application/json' \ - http://127.0.0.1:7777/v1/primary/status - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``DELETE`` request. - -DELETE /v1/primary -~~~~~~~~~~~~~~~~~~ - -Terminate primary process. - -* Normal response codes: 204 - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X DELETE -H 'application/json' \ - http://127.0.0.1:7777/v1/primary - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``DELETE`` request. - - -API for spp_nfv/spp_vm ----------------------- - -GET /v1/nfvs/{client_id} -~~~~~~~~~~~~~~~~~~~~~~~~ - -Get the information of the ``spp_nfv`` or ``spp_vm`` process. - -* Normal response codes: 200 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_nfvs_get: - -.. table:: Request parameter for getting spp_nfv or spp_vm info. - - +-----------+---------+-------------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+=====================================+ - | client_id | integer | client id. | - +-----------+---------+-------------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X GET -H 'application/json' \ - http://127.0.0.1:7777/v1/nfvs/1 - -Response -^^^^^^^^ - -.. _table_spp_ctl_spp_nfv_res: - -.. table:: Response params of getting spp_nfv or spp_vm info. - - +-----------+---------+---------------------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+=============================================+ - | client-id | integer | client id. | - +-----------+---------+---------------------------------------------+ - | status | string | ``Running`` or ``Idle``. | - +-----------+---------+---------------------------------------------+ - | ports | array | an array of port ids used by the process. | - +-----------+---------+---------------------------------------------+ - | patches | array | an array of patches. | - +-----------+---------+---------------------------------------------+ - -patch objest - -.. _table_spp_ctl_patch_spp_nfv: - -.. table:: Attributes of patch of spp_nfv or spp_vm. - - +------+--------+----------------------------------------------+ - | Name | Type | Description | - | | | | - +======+========+==============================================+ - | src | string | source port id. | - +------+--------+----------------------------------------------+ - | dst | string | destination port id. | - +------+--------+----------------------------------------------+ - -Response example -^^^^^^^^^^^^^^^^ - -.. code-block:: json - - { - "client-id": 1, - "status": "Running", - "ports": [ - "phy:0", "phy:1", "vhost:0", "vhost:1", "ring:0", "ring:1", "ring:2", "ring:3" - ], - "patches": [ - { - "src": "vhost:0", "dst": "ring:0" - }, - { - "src": "ring:1", "dst": "vhost:1" - } - ] - } - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - sec {client_id};status - - -PUT /v1/nfvs/{client_id}/forward -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Start or Stop forwarding. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_nfv_forward_get: - -.. table:: Request params of forward of spp_nfv or spp_vm. - - +-----------+---------+---------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+=================================+ - | client_id | integer | client id. | - +-----------+---------+---------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X PUT -H 'application/json' \ - -d '{"action": "start"}' \ - http://127.0.0.1:7777/v1/nfvs/1/forward - -Request(body) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_nfv_forward_get_body: - -.. table:: Request body params of forward of spp_nfv or spp_vm. - - +--------+--------+-------------------------------------+ - | Name | Type | Description | - | | | | - +========+========+=====================================+ - | action | string | ``start`` or ``stop``. | - +--------+--------+-------------------------------------+ - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``PUT`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -action is ``start`` - -.. code-block:: none - - sec {client_id};forward - -action is ``stop`` - -.. code-block:: none - - sec {client_id};stop - - -PUT /v1/nfvs/{client_id}/ports -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Add or Delete port. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_nfv_ports_get: - -.. table:: Request params of ports of spp_nfv or spp_vm. - - +-----------+---------+--------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+================================+ - | client_id | integer | client id. | - +-----------+---------+--------------------------------+ - -Request(body) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_nfv_ports_get_body: - -.. table:: Request body params of ports of spp_nfv or spp_vm. - - +--------+--------+---------------------------------------------------------------+ - | Name | Type | Description | - | | | | - +========+========+===============================================================+ - | action | string | ``add`` or ``del``. | - +--------+--------+---------------------------------------------------------------+ - | port | string | port id. port id is the form {interface_type}:{interface_id}. | - +--------+--------+---------------------------------------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X PUT -H 'application/json' \ - -d '{"action": "add", "port": "ring:0"}' \ - http://127.0.0.1:7777/v1/nfvs/1/ports - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``PUT`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - sec {client_id};{action} {interface_type} {interface_id} - - -PUT /v1/nfvs/{client_id}/patches -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Add a patch. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_nfv_patches_get: - -.. table:: Request params of patches of spp_nfv or spp_vm. - - +-----------+---------+---------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+=================================+ - | client_id | integer | client id. | - +-----------+---------+---------------------------------+ - -Request(body) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_nfv_ports_patches_body: - -.. table:: Request body params of patches of spp_nfv or spp_vm. - - +------+--------+------------------------------------+ - | Name | Type | Description | - | | | | - +======+========+====================================+ - | src | string | source port id. | - +------+--------+------------------------------------+ - | dst | string | destination port id. | - +------+--------+------------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X PUT -H 'application/json' \ - -d '{"src": "ring:0", "dst": "ring:1"}' \ - http://127.0.0.1:7777/v1/nfvs/1/patches - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``PUT`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - sec {client_id};patch {src} {dst} - - -DELETE /v1/nfvs/{client_id}/patches -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Reset patches. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_nfv_del_patches: - -.. table:: Request params of deleting patches of spp_nfv or spp_vm. - - +-----------+---------+---------------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+=======================================+ - | client_id | integer | client id. | - +-----------+---------+---------------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X DELETE -H 'application/json' \ - http://127.0.0.1:7777/v1/nfvs/1/patches - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``DELETE`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - sec {client_id};patch reset - - -DELETE /v1/nfvs/{client_id} -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Terminate ``spp_nfv`` or ``spp_vm`` process. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_nfvs_delete: - -.. table:: Request parameter for terminating spp_nfv or spp_vm. - - +-----------+---------+-------------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+=====================================+ - | client_id | integer | client id. | - +-----------+---------+-------------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X DELETE -H 'application/json' \ - http://127.0.0.1:7777/v1/nfvs/1 - -Response example -^^^^^^^^^^^^^^^^ - -There is no body content for the response of a successful ``DELETE`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - sec {client_id}; exit - - -API for spp_vf --------------- - -GET /v1/vfs/{client_id} -~~~~~~~~~~~~~~~~~~~~~~~ - -Get the information of the ``spp_vf`` process. - -* Normal response codes: 200 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_vfs_get: - -.. table:: Request parameter for getting spp_vf. - - +-----------+---------+--------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+==========================+ - | client_id | integer | client id. | - +-----------+---------+--------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X GET -H 'application/json' \ - http://127.0.0.1:7777/v1/vfs/1 - -Response -^^^^^^^^ - -.. _table_spp_ctl_spp_vf_res: - -.. table:: Response params of getting spp_vf. - - +------------------+---------+-----------------------------------------------+ - | Name | Type | Description | - | | | | - +==================+=========+===============================================+ - | client-id | integer | client id. | - +------------------+---------+-----------------------------------------------+ - | ports | array | an array of port ids used by the process. | - +------------------+---------+-----------------------------------------------+ - | components | array | an array of component objects in the process. | - +------------------+---------+-----------------------------------------------+ - | classifier_table | array | an array of classifier tables in the process. | - +------------------+---------+-----------------------------------------------+ - -component object: - -.. _table_spp_ctl_spp_vf_res_comp: - -.. table:: Component objects of getting spp_vf. - - +---------+---------+---------------------------------------------------------------------+ - | Name | Type | Description | - | | | | - +=========+=========+=====================================================================+ - | core | integer | core id running on the component | - +---------+---------+---------------------------------------------------------------------+ - | name | string | an array of port ids used by the process. | - +---------+---------+---------------------------------------------------------------------+ - | type | string | an array of component objects in the process. | - +---------+---------+---------------------------------------------------------------------+ - | rx_port | array | an array of port objects connected to the rx side of the component. | - +---------+---------+---------------------------------------------------------------------+ - | tx_port | array | an array of port objects connected to the tx side of the component. | - +---------+---------+---------------------------------------------------------------------+ - -port object: - -.. _table_spp_ctl_spp_vf_res_port: - -.. table:: Port objects of getting spp_vf. - - +---------+---------+---------------------------------------------------------------+ - | Name | Type | Description | - | | | | - +=========+=========+===============================================================+ - | port | string | port id. port id is the form {interface_type}:{interface_id}. | - +---------+---------+---------------------------------------------------------------+ - | vlan | object | vlan operation which is applied to the port. | - +---------+---------+---------------------------------------------------------------+ - -vlan object: - -.. _table_spp_ctl_spp_vf_res_vlan: - -.. table:: Vlan objects of getting spp_vf. - - +-----------+---------+-------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+===============================+ - | operation | string | ``add``, ``del`` or ``none``. | - +-----------+---------+-------------------------------+ - | id | integer | vlan id. | - +-----------+---------+-------------------------------+ - | pcp | integer | vlan pcp. | - +-----------+---------+-------------------------------+ - -classifier table: - -.. _table_spp_ctl_spp_vf_res_cls: - -.. table:: Vlan objects of getting spp_vf. - - +-----------+--------+------------------------------------------------------------+ - | Name | Type | Description | - | | | | - +===========+========+============================================================+ - | type | string | ``mac`` or ``vlan``. | - +-----------+--------+------------------------------------------------------------+ - | value | string | mac_address for ``mac``, vlan_id/mac_address for ``vlan``. | - +-----------+--------+------------------------------------------------------------+ - | port | string | port id applied to classify. | - +-----------+--------+------------------------------------------------------------+ - -Response example -^^^^^^^^^^^^^^^^ - -.. code-block:: json - - { - "client-id": 1, - "ports": [ - "phy:0", "phy:1", "vhost:0", "vhost:1", "ring:0", "ring:1", "ring:2", "ring:3" - ], - "components": [ - { - "core": 2, - "name": "forward_0_tx", - "type": "forward", - "rx_port": [ - { - "port": "ring:0", - "vlan": { "operation": "none", "id": 0, "pcp": 0 } - } - ], - "tx_port": [ - { - "port": "vhost:0", - "vlan": { "operation": "none", "id": 0, "pcp": 0 } - } - ] - }, - { - "core": 3, - "type": "unuse" - }, - { - "core": 4, - "type": "unuse" - }, - { - "core": 5, - "name": "forward_1_rx", - "type": "forward", - "rx_port": [ - { - "port": "vhost:1", - "vlan": { "operation": "none", "id": 0, "pcp": 0 } - } - ], - "tx_port": [ - { - "port": "ring:3", - "vlan": { "operation": "none", "id": 0, "pcp": 0 } - } - ] - }, - { - "core": 6, - "name": "classifier", - "type": "classifier_mac", - "rx_port": [ - { - "port": "phy:0", - "vlan": { "operation": "none", "id": 0, "pcp": 0 } - } - ], - "tx_port": [ - { - "port": "ring:0", - "vlan": { "operation": "none", "id": 0, "pcp": 0 } - }, - { - "port": "ring:2", - "vlan": { "operation": "none", "id": 0, "pcp": 0 } - } - ] - }, - { - "core": 7, - "name": "merger", - "type": "merge", - "rx_port": [ - { - "port": "ring:1", - "vlan": { "operation": "none", "id": 0, "pcp": 0 } - }, - { - "port": "ring:3", - "vlan": { "operation": "none", "id": 0, "pcp": 0 } - } - ], - "tx_port": [ - { - "port": "phy:0", - "vlan": { "operation": "none", "id": 0, "pcp": 0 } - } - ] - }, - ], - "classifier_table": [ - { - "type": "mac", - "value": "FA:16:3E:7D:CC:35", - "port": "ring:0" - } - ] - } - -The component which type is ``unused`` is to indicate unused core. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - sec {client_id};status - - -POST /v1/vfs/{client_id}/components -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Start the component. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_vf_components: - -.. table:: Request params of components of spp_vf. - - +-----------+---------+-------------+ - | Name | Type | Description | - +===========+=========+=============+ - | client_id | integer | client id. | - +-----------+---------+-------------+ - - -Request(body) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_vf_components_res: - -.. table:: Response params of components of spp_vf. - - +-----------+---------+----------------------------------------------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+======================================================================+ - | name | string | component name. must be unique in the process. | - +-----------+---------+----------------------------------------------------------------------+ - | core | integer | core id. | - +-----------+---------+----------------------------------------------------------------------+ - | type | string | component type. one of ``forward``, ``merge`` or ``classifier_mac``. | - +-----------+---------+----------------------------------------------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X POST -H 'application/json' \ - -d '{"name": "forwarder1", "core": 12, "type": "forward"}' \ - http://127.0.0.1:7777/v1/vfs/1/components - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``POST`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - sec {client_id};component start {name} {core} {type} - - -DELETE /v1/vfs/{sec id}/components/{name} -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Stop the component. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_vf_del: - -.. table:: Request params of deleting component of spp_vf. - - +-----------+---------+---------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+=================================+ - | client_id | integer | client id. | - +-----------+---------+---------------------------------+ - | name | string | component name. | - +-----------+---------+---------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X DELETE -H 'application/json' \ - http://127.0.0.1:7777/v1/vfs/1/components/forwarder1 - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``POST`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - sec {client_id};component stop {name} - - -PUT /v1/vfs/{client_id}/components/{name}/ports -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Add or Delete port to the component. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_vf_comp_port: - -.. table:: Request params for ports of component of spp_vf. - - +-----------+---------+---------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+===========================+ - | client_id | integer | client id. | - +-----------+---------+---------------------------+ - | name | string | component name. | - +-----------+---------+---------------------------+ - -Request(body) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_vf_comp_port_body: - -.. table:: Request body params for ports of component of spp_vf. - - +---------+---------+-----------------------------------------------------------------+ - | Name | Type | Description | - | | | | - +=========+=========+=================================================================+ - | action | string | ``attach`` or ``detach``. | - +---------+---------+-----------------------------------------------------------------+ - | port | string | port id. port id is the form {interface_type}:{interface_id}. | - +---------+---------+-----------------------------------------------------------------+ - | dir | string | ``rx`` or ``tx``. | - +---------+---------+-----------------------------------------------------------------+ - | vlan | object | vlan operation which is applied to the port. it can be omitted. | - +---------+---------+-----------------------------------------------------------------+ - -vlan object: - -.. _table_spp_ctl_spp_vf_comp_port_body_vlan: - -.. table:: Request body params for vlan ports of component of spp_vf. - - +-----------+---------+----------------------------------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+==========================================================+ - | operation | string | ``add``, ``del`` or ``none``. | - +-----------+---------+----------------------------------------------------------+ - | id | integer | vlan id. ignored when operation is ``del`` or ``none``. | - +-----------+---------+----------------------------------------------------------+ - | pcp | integer | vlan pcp. ignored when operation is ``del`` or ``none``. | - +-----------+---------+----------------------------------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X PUT -H 'application/json' \ - -d '{"action": "attach", "port": "vhost:1", "dir": "rx", \ - "vlan": {"operation": "add", "id": 677, "pcp": 0}}' \ - http://127.0.0.1:7777/v1/vfs/1/components/forwarder1/ports - -.. code-block:: console - - curl -X PUT -H 'application/json' \ - -d '{"action": "detach", "port": "vhost:0", "dir": "tx"} \ - http://127.0.0.1:7777/v1/vfs/1/components/forwarder1/ports - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``PUT`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -action is ``attach`` - -.. code-block:: none - - sec {client_id};port add {port} {dir} {name} [add_vlantag {id} {pcp} | del_vlantag] - -action is ``detach`` - -.. code-block:: none - - sec {client_id};port del {port} {dir} {name} - - -PUT /v1/vfs/{sec id}/classifier_table -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Set or Unset classifier table. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_vf_cls_table: - -.. table:: Request params for classifier_table of spp_vf. - - +-----------+---------+---------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+===========================+ - | client_id | integer | client id. | - +-----------+---------+---------------------------+ - -Request(body) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_vf_cls_table_body: - -.. table:: Request body params for classifier_table of spp_vf. - - +-------------+-----------------+----------------------------------------------------+ - | Name | Type | Description | - | | | | - +=============+=================+====================================================+ - | action | string | ``add`` or ``del``. | - +-------------+-----------------+----------------------------------------------------+ - | type | string | ``mac`` or ``vlan``. | - +-------------+-----------------+----------------------------------------------------+ - | vlan | integer or null | vlan id for ``vlan``. null or omitted for ``mac``. | - +-------------+-----------------+----------------------------------------------------+ - | mac_address | string | mac address. | - +-------------+-----------------+----------------------------------------------------+ - | port | string | port id. | - +-------------+-----------------+----------------------------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X PUT -H 'application/json' \ - -d '{"action": "add", "type": "mac", "mac_address": "FA:16:3E:7D:CC:35", \ - "port": "ring:0"}' \ - http://127.0.0.1:7777/v1/vfs/1/classifier_table - -.. code-block:: console - - curl -X PUT -H 'application/json' \ - -d '{"action": "del", "type": "vlan", "vlan": 475, \ - "mac_address": "FA:16:3E:7D:CC:35", "port": "ring:0"}' \ - http://127.0.0.1:7777/v1/vfs/1/classifier_table - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``PUT`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -type is ``mac`` - -.. code-block:: none - - classifier_table {action} mac {mac_address} {port} - -type is ``vlan`` - -.. code-block:: none - - classifier_table {action} vlan {vlan} {mac_address} {port} - - -API for spp_mirror ------------------- - -GET /v1/mirrors/{client_id} -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Get the information of the ``spp_mirror`` process. - -* Normal response codes: 200 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_mirrors_get: - -.. table:: Request parameter for getting spp_mirror. - - +-----------+---------+--------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+==========================+ - | client_id | integer | client id. | - +-----------+---------+--------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X GET -H 'application/json' \ - http://127.0.0.1:7777/v1/mirrors/1 - -Response -^^^^^^^^ - -.. _table_spp_ctl_spp_mirror_res: - -.. table:: Response params of getting spp_mirror. - - +------------------+---------+-----------------------------------------------+ - | Name | Type | Description | - | | | | - +==================+=========+===============================================+ - | client-id | integer | client id. | - +------------------+---------+-----------------------------------------------+ - | ports | array | an array of port ids used by the process. | - +------------------+---------+-----------------------------------------------+ - | components | array | an array of component objects in the process. | - +------------------+---------+-----------------------------------------------+ - -component object: - -.. _table_spp_ctl_spp_mirror_res_comp: - -.. table:: Component objects of getting spp_mirror. - - +---------+---------+---------------------------------------------------------------------+ - | Name | Type | Description | - | | | | - +=========+=========+=====================================================================+ - | core | integer | core id running on the component | - +---------+---------+---------------------------------------------------------------------+ - | name | string | an array of port ids used by the process. | - +---------+---------+---------------------------------------------------------------------+ - | type | string | an array of component objects in the process. | - +---------+---------+---------------------------------------------------------------------+ - | rx_port | array | an array of port objects connected to the rx side of the component. | - +---------+---------+---------------------------------------------------------------------+ - | tx_port | array | an array of port objects connected to the tx side of the component. | - +---------+---------+---------------------------------------------------------------------+ - -port object: - -.. _table_spp_ctl_spp_mirror_res_port: - -.. table:: Port objects of getting spp_vf. - - +---------+---------+---------------------------------------------------------------+ - | Name | Type | Description | - | | | | - +=========+=========+===============================================================+ - | port | string | port id. port id is the form {interface_type}:{interface_id}. | - +---------+---------+---------------------------------------------------------------+ - -Response example -^^^^^^^^^^^^^^^^ - -.. code-block:: json - - { - "client-id": 1, - "ports": [ - "phy:0", "phy:1", "ring:0", "ring:1", "ring:2" - ], - "components": [ - { - "core": 2, - "name": "mirror_0", - "type": "mirror", - "rx_port": [ - { - "port": "ring:0" - } - ], - "tx_port": [ - { - "port": "ring:1" - }, - { - "port": "ring:2" - } - ] - }, - { - "core": 3, - "type": "unuse" - } - ] - } - -The component which type is ``unused`` is to indicate unused core. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - sec {client_id};status - - -POST /v1/mirrors/{client_id}/components -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Start the component. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_mirror_components: - -.. table:: Request params of components of spp_mirror. - - +-----------+---------+-------------+ - | Name | Type | Description | - +===========+=========+=============+ - | client_id | integer | client id. | - +-----------+---------+-------------+ - - -Request(body) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_mirror_components_res: - -.. table:: Response params of components of spp_mirror. - - +-----------+---------+----------------------------------------------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+======================================================================+ - | name | string | component name. must be unique in the process. | - +-----------+---------+----------------------------------------------------------------------+ - | core | integer | core id. | - +-----------+---------+----------------------------------------------------------------------+ - | type | string | component type. only ``mirror`` is available. | - +-----------+---------+----------------------------------------------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X POST -H 'application/json' \ - -d '{"name": "mirror_1", "core": 12, "type": "mirror"}' \ - http://127.0.0.1:7777/v1/mirrors/1/components - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``POST`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - sec {client_id};component start {name} {core} {type} - - -DELETE /v1/mirrors/{client_id}/components/{name} -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Stop the component. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_mirror_del: - -.. table:: Request params of deleting component of spp_mirror. - - +-----------+---------+---------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+=================================+ - | client_id | integer | client id. | - +-----------+---------+---------------------------------+ - | name | string | component name. | - +-----------+---------+---------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X DELETE -H 'application/json' \ - http://127.0.0.1:7777/v1/mirrors/1/components/mirror_1 - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``POST`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - sec {client_id};component stop {name} - - -PUT /v1/mirrors/{client_id}/components/{name}/ports -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Add or Delete port to the component. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_mirror_comp_port: - -.. table:: Request params for ports of component of spp_mirror. - - +-----------+---------+---------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+===========================+ - | client_id | integer | client id. | - +-----------+---------+---------------------------+ - | name | string | component name. | - +-----------+---------+---------------------------+ - -Request(body) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_mirror_comp_port_body: - -.. table:: Request body params for ports of component of spp_mirror. - - +---------+---------+-----------------------------------------------------------------+ - | Name | Type | Description | - | | | | - +=========+=========+=================================================================+ - | action | string | ``attach`` or ``detach``. | - +---------+---------+-----------------------------------------------------------------+ - | port | string | port id. port id is the form {interface_type}:{interface_id}. | - +---------+---------+-----------------------------------------------------------------+ - | dir | string | ``rx`` or ``tx``. | - +---------+---------+-----------------------------------------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X PUT -H 'application/json' \ - -d '{"action": "attach", "port": "ring:1", "dir": "rx"}' \ - http://127.0.0.1:7777/v1/mirrors/1/components/mirror_1/ports - -.. code-block:: console - - curl -X PUT -H 'application/json' \ - -d '{"action": "detach", "port": "ring:0", "dir": "tx"} \ - http://127.0.0.1:7777/v1/mirrors/1/components/mirror_1/ports - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``PUT`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -action is ``attach`` - -.. code-block:: none - - sec {client_id};port add {port} {dir} {name} - -action is ``detach`` - -.. code-block:: none - - sec {client_id};port del {port} {dir} {name} - - -API for spp_pcap ----------------- - -GET /v1/pcaps/{client_id} -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Get the information of the ``spp_pcap`` process. - -* Normal response codes: 200 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_pcap_get: - -.. table:: Request parameter for getting spp_pcap info. - - +-----------+---------+-------------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+=====================================+ - | client_id | integer | client id. | - +-----------+---------+-------------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X GET -H 'application/json' \ - http://127.0.0.1:7777/v1/pcaps/1 - -Response -^^^^^^^^ - -.. _table_spp_ctl_spp_pcap_res: - -.. table:: Response params of getting spp_pcap. - - +------------------+---------+-----------------------------------------------+ - | Name | Type | Description | - | | | | - +==================+=========+===============================================+ - | client-id | integer | client id. | - +------------------+---------+-----------------------------------------------+ - | status | string | status of the process. "running" or "idle". | - +------------------+---------+-----------------------------------------------+ - | core | array | an array of core objects in the process. | - +------------------+---------+-----------------------------------------------+ - -core object: - -.. _table_spp_ctl_spp_pcap_res_core: - -.. table:: Core objects of getting spp_pcap. - - +----------+---------+----------------------------------------------------------------------+ - | Name | Type | Description | - | | | | - +==========+=========+======================================================================+ - | core | integer | core id | - +----------+---------+----------------------------------------------------------------------+ - | role | string | role of the task running on the core. "receive" or "write". | - +----------+---------+----------------------------------------------------------------------+ - | rx_port | array | an array of port object for caputure. This member exists if role is | - | | | "recieve". Note that there is only a port object in the array. | - +----------+---------+----------------------------------------------------------------------+ - | filename | string | a path name of output file. This member exists if role is "write". | - +----------+---------+----------------------------------------------------------------------+ - -Note that there is only a port object in the array - -port object: - -.. _table_spp_ctl_spp_pcap_res_port: - -.. table:: Port objects of getting spp_pcap. - - +---------+---------+---------------------------------------------------------------+ - | Name | Type | Description | - | | | | - +=========+=========+===============================================================+ - | port | string | port id. port id is the form {interface_type}:{interface_id}. | - +---------+---------+---------------------------------------------------------------+ - -Response example -^^^^^^^^^^^^^^^^ - -.. code-block:: json - - { - "client-id": 1, - "status": "running", - "core": [ - { - "core": 2, - "role": "receive", - "rx_port": [ - { - "port": "phy:0" - } - ] - }, - { - "core": 3, - "role": "write", - "filename": "/tmp/spp_pcap.20181108110600.ring0.1.2.pcap" - } - ] - } - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - pcap {client_id}; status - -PUT /v1/pcaps/{client_id}/capture -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Start or Stop capturing. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_pcap_capture: - -.. table:: Request params of capture of spp_pcap. - - +-----------+---------+---------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+=================================+ - | client_id | integer | client id. | - +-----------+---------+---------------------------------+ - -Request(body) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_spp_pcap_capture_body: - -.. table:: Request body params of capture of spp_pcap. - - +--------+--------+-------------------------------------+ - | Name | Type | Description | - | | | | - +========+========+=====================================+ - | action | string | ``start`` or ``stop``. | - +--------+--------+-------------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X PUT -H 'application/json' \ - -d '{"action": "start"}' \ - http://127.0.0.1:7777/v1/pcaps/1/capture - -Response -^^^^^^^^ - -There is no body content for the response of a successful ``PUT`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -action is ``start`` - -.. code-block:: none - - pcap {client_id}; start - -action is ``stop`` - -.. code-block:: none - - pcap {client_id}; stop - - -DELETE /v1/pcaps/{client_id} -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Terminate ``spp_pcap`` process. - -* Normal response codes: 204 -* Error response codes: 400, 404 - -Request(path) -^^^^^^^^^^^^^ - -.. _table_spp_ctl_pcap_delete: - -.. table:: Request parameter for terminating spp_pcap. - - +-----------+---------+-------------------------------------+ - | Name | Type | Description | - | | | | - +===========+=========+=====================================+ - | client_id | integer | client id. | - +-----------+---------+-------------------------------------+ - -Request example -^^^^^^^^^^^^^^^ - -.. code-block:: console - - curl -X DELETE -H 'application/json' \ - http://127.0.0.1:7777/v1/pcaps/1 - -Response example -^^^^^^^^^^^^^^^^ - -There is no body content for the response of a successful ``DELETE`` request. - -Equivalent CLI command -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - pcap {client_id}; exit diff --git a/docs/guides/spp-ctl/index.rst b/docs/guides/spp-ctl/index.rst deleted file mode 100644 index 499bcfe..0000000 --- a/docs/guides/spp-ctl/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. SPDX-License-Identifier: BSD-3-Clause - Copyright(c) 2018 Nippon Telegraph and Telephone Corporation - -.. _spp_ctl_index: - -spp-ctl -======= - -.. toctree:: - :maxdepth: 2 - :numbered: - - overview - api-reference diff --git a/docs/guides/spp-ctl/overview.rst b/docs/guides/spp-ctl/overview.rst deleted file mode 100644 index 6b88f3b..0000000 --- a/docs/guides/spp-ctl/overview.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. SPDX-License-Identifier: BSD-3-Clause - Copyright(c) 2018 Nippon Telegraph and Telephone Corporation - -.. _spp_ctl_overview: - -spp-ctl -======= - -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.7.4