From dba214e25100af9c93633ff4b7e476e7c124bc3c Mon Sep 17 00:00:00 2001 From: hanchao Date: Wed, 13 Apr 2016 17:02:39 +0800 Subject: [PATCH] Restructure the docs for steth Reformat the README.md into README.rst. Reschedule the directory of the docs. Add code blocks to emphasize the commands in the quickstart.rst. Seperate the multi-node- architecture section out of the README.rst, and put it in the multi-node-architecture.rst. Note: The multi-node-architecture.rst is not indicated in the README.rst. Change-Id: I05407cf75e4f140158c690d96a9ded5f39cf6bc8 Closes-Bug: #1569139 --- README.md | 96 --------------------- README.rst | 50 +++++++++++ {doc => docs}/Makefile | 4 +- {doc/source => docs}/conf.py | 0 docs/index.rst | 49 +++++++++++ doc/source/index.rst => docs/quickstart.rst | 15 ++-- multi-node-architecture.rst | 62 +++++++++++++ setup.cfg | 2 +- 8 files changed, 173 insertions(+), 105 deletions(-) delete mode 100644 README.md create mode 100644 README.rst rename {doc => docs}/Makefile (98%) rename {doc/source => docs}/conf.py (100%) create mode 100644 docs/index.rst rename doc/source/index.rst => docs/quickstart.rst (83%) create mode 100644 multi-node-architecture.rst diff --git a/README.md b/README.md deleted file mode 100644 index e4c0b9b..0000000 --- a/README.md +++ /dev/null @@ -1,96 +0,0 @@ -# Steth - -A network inspection tool for OpenStack. - - - * License: Apache License, Version 2.0 - * Source: https://git.openstack.org/cgit/openstack/steth - * Bugs: https://bugs.launchpad.net/steth - * Wiki: https://wiki.openstack.org/wiki/Steth - - -## Description - -Steth is an inspection tool that can aid in pinpointing issues before deployment -and during operation of an OpenStack environment. - -It is modelled as agent(s)/client in which a controller interacts with agents -deployed in your environment. - - -## Background - -OpenStack networking can be deloyed as different architectures, such as ML2 with -OVS(legacy and DVR), Linux bridge, OVN, Dragonflow and so forth. However, they -all need enviromental prerequisites. For instance, VLAN needs to be configured -as we expect; bandwidth should meet our requirements; connection between nodes -should be active, etc. - -Besides, with some well-deployed architectures, troubleshooting for VM -networking is difficult. For instance, why VM cannot get an IP address; or why -it cannot connect to Internet, etc. Steth integrates useful scripts and third -party tools(like iperf, tcpdump, etc.) to help operators keep tracking on VM -networking. - - -## Mission - -Steth is an introspection tool for OpenStack networking. Only proved to be -working in ML2 with OVS for now. - - -## Multi-node Architecture - -``` - note that steth does not save - any state, it acts as a rpc - client which makes requests to steth - +--------------------------+ agent(s) and analyses the result. - | | - | +------CLI---------+ | - | | | | - +--------------------------+ steth +--------------------------+ - | | | | | | - | | +--------+---------+ | | - | | | | | - | +--------------------------+ | - | | | - v v v -+-------+port:9698---------+ +-------+port:9698---------+ +-------+port:9698---------+ -| ^ | | ^ | | ^ | -| | | | | | | | | -| +----------+-------+ | | +----------+-------+ | | +----------+-------+ | -| | | | | | | | | | | | -| | steth-agent | | | | steth-agent | | | | steth-agent | | -| | | | | | | | | | | | -| +-----------+------+ | | +-----------+------+ | | +-----------+------+ | -| | | | | | | | | -| | | | | | | | | -| +----------v----------+ | | +----------v----------+ | | +----------v----------+ | -| | run command like: | | | | run command like: | | | | run command like: | | -| | ping, iperf, tcpdump| | | | ping, iperf, tcpdump| | | | ping, iperf, tcpdump| | -| | or use scapy to send| | | | or use scapy to send| | | | or use scapy to send| | -| | packet | | | | packet | | | | packet | | -| +---------------------+ | | +---------------------+ | | +---------------------+ | -| | | | | | -| | | | | | -+--------------------------+ +--------------------------+ +--------------------------+ -``` - -In a scenario using multiple nodes, Steth is a stateless CLI and controller. -It knows each steth agent and will read config files, interact with OpenStack, -and sending instructions to agents when needed. - -Steth Agent is introduced to manage processes or run commands. It should be -installed in each compute and network node, and their IPs should be specified -in the config file of steth controller. - - -## Steth Agent - -Listening on 0.0.0.0:9698 and waiting for the rpc request. - -Note: for get_interface() agent API, we use ifconfig to get full information. -However, the output of ifconfig varies from a Linux distribution to another. -The API has only been tested on CentOS 6.5 and 7.0. Any other distribution has -not been tested. If it works, please let us know. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..b25251a --- /dev/null +++ b/README.rst @@ -0,0 +1,50 @@ +===== +Steth +===== + +A network inspection tool for OpenStack. + + + * License: Apache License, Version 2.0 + * Source: https://git.openstack.org/cgit/openstack/steth + * Bugs: https://bugs.launchpad.net/steth + * Wiki: https://wiki.openstack.org/wiki/Steth + * Docs: http://steth.readthedocs.org/ + + +----------- +Description +----------- + +Steth is an inspection tool that can aid in pinpointing issues before deployment +and during operation of an OpenStack environment. + +It is modelled as agent(s)/client in which a controller interacts with agents +deployed in your environment. + + +---------- +Background +---------- + +OpenStack networking can be deloyed as different architectures, such as ML2 with +OVS(legacy and DVR), Linux bridge, OVN, Dragonflow and so forth. However, they +all need enviromental prerequisites. For instance, VLAN needs to be configured +as we expect; bandwidth should meet our requirements; connection between nodes +should be active, etc. + +Besides, with some well-deployed architectures, troubleshooting for VM +networking is difficult. For instance, why VM cannot get an IP address; or why +it cannot connect to Internet, etc. Steth integrates useful scripts and third +party tools(like iperf, tcpdump, etc.) to help operators keep tracking on VM +networking. + + +------- +Mission +------- + +Steth is an introspection tool for OpenStack networking. Only proved to be +working in ML2 with OVS for now. + + diff --git a/doc/Makefile b/docs/Makefile similarity index 98% rename from doc/Makefile rename to docs/Makefile index cc0c07b..75b5484 100644 --- a/doc/Makefile +++ b/docs/Makefile @@ -3,9 +3,9 @@ # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build -SPHINXSOURCE = source +SPHINXSOURCE = . PAPER = -BUILDDIR = build +BUILDDIR = _build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 diff --git a/doc/source/conf.py b/docs/conf.py similarity index 100% rename from doc/source/conf.py rename to docs/conf.py diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..c53968d --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,49 @@ +===== +Steth +===== + +A network inspection tool for OpenStack. + + + * License: Apache License, Version 2.0 + * Source: https://git.openstack.org/cgit/openstack/steth + * Bugs: https://bugs.launchpad.net/steth + * Wiki: https://wiki.openstack.org/wiki/Steth + * Docs: http://steth.readthedocs.org/ + +----------- +Description +----------- + +Steth is an inspection tool that can aid in pinpointing issues before deployment +and during operation of an OpenStack environment. + +It is modelled as agent(s)/client in which a controller interacts with agents +deployed in your environment. + + +---------- +Background +---------- + +OpenStack networking can be deloyed as different architectures, such as ML2 with +OVS(legacy and DVR), Linux bridge, OVN, Dragonflow and so forth. However, they +all need enviromental prerequisites. For instance, VLAN needs to be configured +as we expect; bandwidth should meet our requirements; connection between nodes +should be active, etc. + +Besides, with some well-deployed architectures, troubleshooting for VM +networking is difficult. For instance, why VM cannot get an IP address; or why +it cannot connect to Internet, etc. Steth integrates useful scripts and third +party tools(like iperf, tcpdump, etc.) to help operators keep tracking on VM +networking. + + +------- +Mission +------- + +Steth is an introspection tool for OpenStack networking. Only proved to be +working in ML2 with OVS for now. + + diff --git a/doc/source/index.rst b/docs/quickstart.rst similarity index 83% rename from doc/source/index.rst rename to docs/quickstart.rst index 11e0452..30b25a4 100644 --- a/doc/source/index.rst +++ b/docs/quickstart.rst @@ -27,11 +27,12 @@ Steth is a network inspection tool for OpenStack. It is modelled as agent(s)/client in which a controller interacts with agents deployed in your environment. Let me introduce how to use steth. + Download code ------------- -Download the latest code from git repository. And run `python setup.py install` -to install steth. After running that, you can `steth - -help` to confirm Steth +Download the latest code from git repository. And run ``python setup.py install`` +to install steth. After running that, you can ``steth - -help`` to confirm Steth is installed correctly. @@ -40,19 +41,21 @@ Deploy Steth Agent Steth Agent listens in 0.0.0.0:9698 on any node you want. It will wait for RPC request. Currently we support CentOS 6.5, CentOS 7.0 and CentOS 7.1 only. -In CentOS 6.5, you should run `service steth-agent start` to start steth-agent. -In CentOS 7.0 and 7.1, you should run `systemctl start steth` to start steth-agent. +In CentOS 6.5, you should run ``service steth-agent start`` to start steth-agent. +In CentOS 7.0 and 7.1, you should run ``systemctl start steth`` to start steth-agent. + Deploy Steth Client ------------------- -Steth Client is a stateless program. You can run `steth - -help` to show all steth +Steth Client is a stateless program. You can run ``steth - -help`` to show all steth commands that you can run. + Configuration File --------------------- -On start the client will read a configuration file. By default the configuration file is located at /etc/steth/steth.conf. +On start the client will read a configuration file. By default the configuration file is located at `/etc/steth/steth.conf`. Here is an example about the configuration file: :: # (ListOpt) list of networks types. diff --git a/multi-node-architecture.rst b/multi-node-architecture.rst new file mode 100644 index 0000000..bfe40cd --- /dev/null +++ b/multi-node-architecture.rst @@ -0,0 +1,62 @@ +----------------------- +Multi-node Architecture +----------------------- + +:: + + note that steth does not save + any state, it acts as a rpc + client which makes requests to steth + +--------------------------+ agent(s) and analyses the result. + | | + | +------CLI---------+ | + | | | | + +--------------------------+ steth +--------------------------+ + | | | | | | + | | +--------+---------+ | | + | | | | | + | +--------------------------+ | + | | | + v v v + +-------+port:9698---------+ +-------+port:9698---------+ +-------+port:9698---------+ + | ^ | | ^ | | ^ | + | | | | | | | | | + | +----------+-------+ | | +----------+-------+ | | +----------+-------+ | + | | | | | | | | | | | | + | | steth-agent | | | | steth-agent | | | | steth-agent | | + | | | | | | | | | | | | + | +-----------+------+ | | +-----------+------+ | | +-----------+------+ | + | | | | | | | | | + | | | | | | | | | + | +----------v----------+ | | +----------v----------+ | | +----------v----------+ | + | | run command like: | | | | run command like: | | | | run command like: | | + | | ping, iperf, tcpdump| | | | ping, iperf, tcpdump| | | | ping, iperf, tcpdump| | + | | or use scapy to send| | | | or use scapy to send| | | | or use scapy to send| | + | | packet | | | | packet | | | | packet | | + | +---------------------+ | | +---------------------+ | | +---------------------+ | + | | | | | | + | | | | | | + +--------------------------+ +--------------------------+ +--------------------------+ + + +In a scenario using multiple nodes, Steth is a stateless CLI and controller. +It knows each steth agent and will read config files, interact with OpenStack, +and sending instructions to agents when needed. + +Steth Agent is introduced to manage processes or run commands. It should be +installed in each compute and network node, and their IPs should be specified +in the config file of steth controller. + + +----------- +Steth Agent +----------- + +Listening on 0.0.0.0:9698 and waiting for the rpc request. + +Note: for get_interface() agent API, we use ifconfig to get full information. +However, the output of ifconfig varies from a Linux distribution to another. +The API has only been tested on CentOS 6.5 and 7.0. Any other distribution has +not been tested. If it works, please let us know. + + diff --git a/setup.cfg b/setup.cfg index 659af3f..bf189a0 100644 --- a/setup.cfg +++ b/setup.cfg @@ -2,7 +2,7 @@ name = steth summary = Steth is a sophisticated debug bridge for OpenStack Neutron. description-file = - README.md + README.rst author = "UnitedStackSDN" author-email = unitedstack-sdn@googlegroups.com home-page = https://www.ustack.com/