x/steth
Code Issues Proposed changes

Restructure the docs for steth

Browse Source 
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
This commit is contained in:
hanchao 2016-04-13 17:02:39 +08:00
parent e381bfda10
commit dba214e251
8 changed files with 173 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
README.md
View File

@ -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.

50
README.rst Normal file
View File

@ -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.

4
doc/Makefile → docs/Makefile
View File

@ -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

0
doc/source/conf.py → docs/conf.py
View File

49
docs/index.rst Normal file
View File

@ -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.

15
doc/source/index.rst → docs/quickstart.rst
View File

@ -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.

62
multi-node-architecture.rst Normal file
View File

@ -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.

2
setup.cfg
View File

@ -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/