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
|
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Convention for heading levels in Open vSwitch documentation:
======= Heading 0 (reserved for the title in a document)
------- Heading 1
~~~~~~~ Heading 2
+++++++ Heading 3
''''''' Heading 4
Avoid deeper levels because they do not render well.
============
Open vSwitch
============
The ``openvswitch`` package provides the `official Python language bindings`__
for `Open vSwitch`__. They are developed in-tree as part of the `Open vSwitch
Package`__.
.. __: https://docs.openvswitch.org/en/latest/topics/language-bindings/
.. __: https://docs.openvswitch.org/en/latest/
.. __: https://github.com/openvswitch/ovs/tree/main/python/ovs
Installation
------------
You can install the package using ``pip``:
.. code-block:: shell
$ pip install ovs
The package include an optional flow parsing library. To use this package, you
must install its required dependencies. The ``flow`` `extra`__ is provided for
this purpose:
.. code-block:: shell
$ pip install ovs[flow]
.. __: https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-extras
Examples
--------
.. _example-database-schema:
Inspecting the database schema
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The OVSDB schema is described in a JSON file, typically called
``vswitch.ovsschema``. It can be inspected via schema provided locally on the
host or remotely via the JSON-RPC API. For example, to view it from the local
file:
.. code-block:: python
import json
import ovs.dirs
schema_path = f'{ovs.dirs.PKGDATADIR}/vswitch.ovsschema'
with open(schema_path) as fh:
schema = json.load(fh)
print(schema)
To do the same via the JSON-RPC, using TCP:
.. code-block:: python
import json
import sys
import ovs.jsonrpc
remote = 'tcp:127.0.0.1:6640'
error, stream = ovs.stream.Stream.open_block(ovs.stream.Stream.open(remote))
if error:
print(error)
sys.exit(1)
rpc = ovs.jsonrpc.Connection(stream)
request = ovs.jsonrpc.Message.create_request('get_schema', ['Open_vSwitch'])
error, reply = rpc.transact_block(request)
rpc.close()
if error:
print(error)
sys.exit(1)
schema = reply.result
print(schema)
.. note::
The above assumes the default port (``6640``) is used and Open vSwitch is
running on the localhost (``127.0.0.1``).
.. _example-dumping-tables-ports-interfaces:
Dumping tables, ports and interfaces
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Open vSwitch Database (OVSDB) Interface Definition Language (IDL) maintains
an in-memory replica of a database. It issues RPC requests to an OVSDB database
server and parses the responses, converting raw JSON into data structures that
are easier for clients to digest. You can use the IDL for database transactions
along with simpler operations such as dumping information about the schema.
The Python implementation of the OVSDB IDL is provided in ``ovs.db.idl`` via
the ``Idl`` class. To initialise this, you need a schema helper and a "remote"
or interface through which to communicate with the OVSDB. We can re-use and
build upon the `schema example from above <example-database-schema>`__ to
create an instance of ``ovs.db.idl.SchemaHelper``. Once done, you can create an
instance of ``ovs.db.idl.IDL`` and use this to iterate over the bridges, ports
and interfaces available:
.. code-block:: python
import ovs.db.idl
import ovs.dirs
# Create the schema helper.
schema_path = f'{ovs.dirs.PKGDATADIR}/vswitch.ovsschema'
schema_helper = ovs.db.idl.SchemaHelper(schema_path)
schema_helper.register_all() # Register all tables for monitoring.
# Connect over TCP.
remote = 'tcp:127.0.0.1:6640'
idl = ovs.db.idl.Idl(remote, schema_helper)
# Wait until we have all information retrieved from the database.
while not idl.has_ever_connected():
poller = ovs.poller.Poller()
idl.wait(poller)
poller.block()
idl.run()
# Print bridges, ports and interfaces, à la 'ovs-vsctl show'.
for bridge in idl.tables['Bridge'].rows.values():
print(f'Bridge {bridge.name}')
for port in bridge.ports:
print(f'\tPort {port.name}')
for interface in port.interfaces:
print(f'\t\tInterface {interface.name}')
print(f'\t\t\ttype: {interface.type}')
.. note::
The above connects to OVSDB via TCP. You could also connect via the unix
socket by replacing the `remote` with e.g.
.. code-block:: python
remote = f'unix:{ovs.dirs.RUNDIR}/db.sock'
.. note::
This is only an example. Production code should be prepared for failures
while retrieving information and may wish to incorporate retry logic.
Documentation
-------------
Documentation is included in the Python source. To view this, you can install
the package and use `pydoc`__. For example:
.. code-block:: shell
$ python -m pydoc ovs
Alternatively, you can use the ``help`` function from the Python REPL:
.. code-block:: python
>>> import ovs
>>> help(ovs)
.. __: https://docs.python.org/3/library/pydoc.html
|
