summaryrefslogtreecommitdiff
path: root/docs/guides/commands/experimental.rst
blob: c328c7318ff6f8d374ef0e83b9708bded47202d6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
..  SPDX-License-Identifier: BSD-3-Clause
    Copyright(c) 2017-2019 Nippon Telegraph and Telephone Corporation


.. _commands_experimental:

Experimental Commands
=====================

There are experimental commands in SPP controller.
It might not work for some cases properly because it is not well tested
currently.


.. _commands_experimental_topo:

topo
----

Output network topology in several formats.
Support four types of output.

* Terminal
* Browser (websocket server is required)
* Text (dot, json, yaml)
* Image file (jpg, png, bmp)

This command uses `graphviz
<https://www.graphviz.org/>`_
for generating topology file.
You can also generate a dot formatted file or image files supported by
graphviz.

Here is an example for installing required tools for ``topo term`` command
to output in a terminal.

.. code-block:: console

    $ sudo apt install graphviz \
      imagemagick \
      libsixel-bin

MacOS is also supported optionally for using topo runs on a remote host.
In this case, iTerm2 and imgcat are required as described in the next
section.

To output in browser with ``topo http`` command, install required packages
by using ``requirements.txt`` as described in
:ref:`install SPP<setup_install_spp>`, or only for them as follwoing.

.. code-block:: console

    $ pip3 install tornado \
      websocket-client


Output to Terminal
~~~~~~~~~~~~~~~~~~

Output an image of network configuration in terminal.

.. code-block:: console

    spp > topo term

There are few terminal applications supporting to output image with ``topo``.
You can use mlterm, xterm or other terminals supported by `img2sixel
<https://github.com/saitoha/libsixel>`_.
You can also use `iTerm2
<https://iterm2.com/index.html>`_ on MacOS.
If you use iTerm2, you need to downloada a shell script
``imgcat`` from `iTerm2's displaying support site
<https://iterm2.com/documentation-images.html>`_
and save this script as
``src/controller/3rd_party/imgcat`` with permission ``775``.
``topo`` command tries to ``img2sixel`` first, then ``imgcat``
in the ``3rd_party`` directory.

.. _figure_topo_term_exp:

.. figure:: ../images/commands/expr/topo_term_exp.*
   :width: 67%

   topo term example


Output to Browser
~~~~~~~~~~~~~~~~~

Output an image of network configuration in browser.

.. code-block:: console

    spp > topo http

``topo term`` is useful to understand network configuration intuitively.
However, it should be executed on a node running SPP controller.
You cannnot see the image if you login remote node via ssh and running
SPP controller on remote.

Websocket server is launched from ``src/controller/websocket/spp_ws.py``
to accept client messages.
You should start it before using ``topo term`` command.
Then, open url shown in the terminal (default is
``http://127.0.0.1:8989``).

Browser and SPP controller behave as clients, but have different roles.
Browser behaves as a viwer and SPP controller behaves as a udpater.
If you update network configuration and run ``topo http`` command,
SPP controller sends a message containing network configuration
as DOT language format.
Once the message is accepted, websocket server sends it to viewer clients
immediately.


Output to File
~~~~~~~~~~~~~~

Output a text or image of network configuration to a file.

.. code-block:: console

    spp > topo [FILE_NAME] [FILE_TYPE]

You do not need to specify ``FILE_TYPE`` because ``topo`` is able to
decide file type from ``FILE_NAME``. It is optional.
This is a list of supported file type.

* dot
* js (or json)
* yml (or yaml)
* jpg
* png
* bmp

To generate a DOT file ``network.dot``, run ``topo`` command with
file name.

.. code-block:: console

    # generate DOT file
    spp > topo network.dot
    Create topology: 'network.dot'
    # show contents of the file
    spp > cat network.dot
    digraph spp{
    newrank=true;
    node[shape="rectangle", style="filled"];
    ...

To generate a jpg image, run ``topo`` with the name ``network.jpg``.

.. code-block:: console

    spp > topo network.jpg
    spp > ls
    ...  network.jpg  ...


.. _commands_experimental_topo_subgraph:

topo_subgraph
-------------

``topo_subgraph`` is a supplemental command for managing subgraphs
for ``topo``.

.. code-block:: console

    spp > topo_subgraph VERB LABEL RES_ID1,RES_ID2,...

Each of options are:

* VERB: ``add`` or ``del``
* LABEL: Arbitrary text, such as ``guest_vm1`` or ``container1``
* RES_ID: Series of Resource ID consists of type and ID such as
  ``vhost:1``. Each of resource IDs are separated with ``,`` or
  ``;``.

Subgraph is a group of object defined in dot language. Grouping objects
helps your understanding relationship or hierarchy of each of objects.
It is used for grouping resources on VM or container to be more
understandable.

For example, if you create two vhost interfaces for a guest VM and patch
them to physical ports, ``topo term`` shows a network configuration as
following.

.. _figure_topo_subg_before:

.. figure:: ../images/commands/expr/topo_subg_before.*
   :width: 67%

   Before using topo_subgraph

Two of vhost interfaces are placed outside of ``Host`` while the guest
VM runs on ``Host``.
However, ``vhost:1`` and ``vhost:2`` should be placed inside ``Host``
actually. It is required to use subgraph!

To include guest VM and its resources inside the ``Host``,
use ``topo_subgraph`` with options.
In this case, add subgraph ``guest_vm`` and includes resoures
``vhost:1`` and ``vhost:2`` into the subgraph.

.. code-block:: console

    spp > topo_subgraph add guest_vm vhost:1,vhost:2

.. _figure_topo_subg_after:

.. figure:: ../images/commands/expr/topo_subg_after.*
   :width: 67%

   After using topo_subgraph

All of registered subgraphs are listed by using ``topo_subgraph``
with no options.

.. code-block:: console

    spp > topo_subgraph
    label: guest_vm subgraph: "vhost:1,vhost:2"

If guest VM is shut down and subgraph is not needed anymore,
delete subgraph ``guest_vm``.

.. code-block:: console

    spp > topo_subgraph del guest_vm


.. _commands_experimental_topo_resize:

topo_resize
-----------

.. note::

    This command will be removed because the size of image is configurable
    with :ref:`config<commands_common_config>` command. You can resize images by changing the value of
    ``topo_size``.

``topo_resize`` is a supplemental command for changing the size of
images displayed on the terminal with ``topo``.

``topo`` displays an image generated from graphviz with default size.
However, it is too small or large for some environments because it
depends on the resolution actually.

To check default size, run ``topo_resize`` with no arguments.
It shows current size of the image.

.. code-block:: console

    # shows current size
    spp > topo_resize
    60%

You can resize it with percentage

.. code-block:: console

    # resize with percentage
    spp > topo_resize 80%
    80%

or ratio.

.. code-block:: console

    # resize with ratio
    spp > topo_resize 0.8
    80%


.. _commands_experimental_load_cmd:

load_cmd
--------

Load command plugin dynamically while running SPP controller.

.. code-block:: console

    spp > load_cmd [CMD_NAME]

CLI of SPP controller is implemented with ``Shell`` class which is
derived from Python standard library ``Cmd``.
It means that subcommands of SPP controller must be implemented as
a member method named as ``do_xxx``.
For instance, ``status`` subcommand is implemented as ``do_status``
method.

``load_cmd`` is for providing a way to define user specific command
as a plugin.
Plugin file must be placed in ``spp/src/controller/command`` and
command name must be the same as file name.
In addition, ``do_xxx`` method must be defined which is called from
SPP controller.

For example, ``hello`` sample plugin is defined as
``spp/src/controller/command/hello.py`` and ``do_hello`` is defined
in this plugin.
Comment for ``do_hello`` is used as help message for ``hello`` command.

.. code-block:: python

    def do_hello(self, name):
        """Say hello to given user

        spp > hello alice
        Hello, alice!
        """

        if name == '':
            print('name is required!')
        else:
            hl = Hello(name)
            hl.say()

``hello`` is loaded and called as following.

.. code-block:: console

    spp > load_cmd hello
    Module 'command.hello' loaded.
    spp > hello alice
    Hello, alice!