Signed-off-by: Stephen Finucane <step...@that.guru> --- v2: Update examples per feedback from v1 --- python/README.rst | 120 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+)
diff --git a/python/README.rst b/python/README.rst index 6d289badb..c22a22a2e 100644 --- a/python/README.rst +++ b/python/README.rst @@ -54,6 +54,126 @@ this purpose: .. __: 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 ------------- -- 2.49.0 _______________________________________________ dev mailing list d...@openvswitch.org https://mail.openvswitch.org/mailman/listinfo/ovs-dev
