diff options
Diffstat (limited to 'doc/developer')
| -rw-r--r-- | doc/developer/building-libyang.rst | 22 | ||||
| -rw-r--r-- | doc/developer/grpc.rst | 282 | ||||
| -rw-r--r-- | doc/developer/topotests.rst | 12 | ||||
| -rw-r--r-- | doc/developer/workflow.rst | 1 |
4 files changed, 292 insertions, 25 deletions
diff --git a/doc/developer/building-libyang.rst b/doc/developer/building-libyang.rst index 5f82447d74..3b33eb3879 100644 --- a/doc/developer/building-libyang.rst +++ b/doc/developer/building-libyang.rst @@ -10,11 +10,12 @@ The FRR project builds some binary ``libyang`` packages. RPM packages are at our `RPM repository <https://rpm.frrouting.org>`_. DEB packages are available as CI artifacts `here -<https://ci1.netdef.org/browse/LIBYANG-LY1REL-DEB10AMD64-4/artifact>`_. +<https://ci1.netdef.org/browse/LIBYANG-LIBYANGV2/latestSuccessful/artifact>`_. .. warning:: - ``libyang`` version 1.0.184 or newer is required to build FRR. + ``libyang`` version 2.0.0 or newer is required to build FRR. Currently a tag + (``v2.0.0``) is used from the libyang2 branch. .. note:: @@ -26,31 +27,22 @@ DEB packages are available as CI artifacts `here Depending on your platform, you may also need to install the PCRE development package. Typically this is ``libpcre-dev`` or ``pcre-devel``. -.. note:: - - For Debian-based systems, the official ``libyang`` package requires recent - versions of ``swig`` (3.0.12) and ``debhelper`` (11) which are only - available in Debian buster (10). However, ``libyang`` packages built on - Debian buster can be installed on both Debian jessie (8) and Debian stretch - (9), as well as various Ubuntu systems. The ``python3-yang`` package will - not work, but the other packages (``libyang-dev`` is the one needed for FRR) - will. - **Option 2: Source Install** .. note:: Ensure that the `libyang build requirements - <https://github.com/CESNET/libyang/blob/master/README.md#build-requirements>`_ + <https://github.com/CESNET/libyang/tree/libyang2#build-requirements>`_ are met before continuing. Usually this entails installing ``cmake`` and ``libpcre-dev`` or ``pcre-devel``. .. code-block:: console - git clone https://github.com/CESNET/libyang.git + git clone https://github.com/CESNET/libyang.git -b libyang2 cd libyang + git checkout v2.0.0 mkdir build; cd build - cmake -DENABLE_LYD_PRIV=ON -DCMAKE_INSTALL_PREFIX:PATH=/usr \ + cmake -D CMAKE_INSTALL_PREFIX:PATH=/usr \ -D CMAKE_BUILD_TYPE:String="Release" .. make sudo make install diff --git a/doc/developer/grpc.rst b/doc/developer/grpc.rst index 8029a08b73..cb164bdabf 100644 --- a/doc/developer/grpc.rst +++ b/doc/developer/grpc.rst @@ -4,6 +4,17 @@ Northbound gRPC *************** +To enable gRPC support one needs to add `--enable-grpc` when running +`configure`. Additionally, when launching each daemon one needs to request +the gRPC module be loaded and which port to bind to. This can be done by adding +`-M grpc:<port>` to the daemon's CLI arguments. + +Currently there is no gRPC "routing" so you will need to bind your gRPC +`channel` to the particular daemon's gRPC port to interact with that daemon's +gRPC northbound interface. + +The minimum version of gRPC known to work is 1.16.1. + .. _grpc-languages-bindings: Programming Language Bindings @@ -17,14 +28,277 @@ next step is to generate the FRR northbound bindings. To generate the northbound bindings you'll need the programming language binding generator tools and those are language specific. -Next sections will use Ruby as an example for writing scripts to use +C++ Example +----------- + +The next sections will use C++ as an example for accessing FRR +northbound through gRPC. + +.. _grpc-c++-generate: + +Generating C++ FRR Bindings +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Generating FRR northbound bindings for C++ example: + +:: + # Install gRPC (e.g., on Ubuntu 20.04) + sudo apt-get install libgrpc++-dev libgrpc-dev + + mkdir /tmp/frr-cpp + cd grpc + + protoc --cpp_out=/tmp/frr-cpp \ + --grpc_out=/tmp/frr-cpp \ + -I $(pwd) \ + --plugin=protoc-gen-grpc=`which grpc_cpp_plugin` \ + frr-northbound.proto + + +.. _grpc-c++-if-sample: + +Using C++ To Get Version and Interfaces State +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Below is a sample program to print all interfaces discovered. + +:: + + # test.cpp + #include <string> + #include <sstream> + #include <grpc/grpc.h> + #include <grpcpp/create_channel.h> + #include "frr-northbound.pb.h" + #include "frr-northbound.grpc.pb.h" + + int main() { + frr::GetRequest request; + frr::GetResponse reply; + grpc::ClientContext context; + grpc::Status status; + + auto channel = grpc::CreateChannel("localhost:50051", + grpc::InsecureChannelCredentials()); + auto stub = frr::Northbound::NewStub(channel); + + request.set_type(frr::GetRequest::ALL); + request.set_encoding(frr::JSON); + request.set_with_defaults(true); + request.add_path("/frr-interface:lib"); + auto stream = stub->Get(&context, request); + + std::ostringstream ss; + while (stream->Read(&reply)) + ss << reply.data().data() << std::endl; + + status = stream->Finish(); + assert(status.ok()); + std::cout << "Interface Info:\n" << ss.str() << std::endl; + } + +Below is how to compile and run the program, with the example output: + +:: + + $ g++ -o test test.cpp frr-northbound.grpc.pb.cc frr-northbound.pb.cc -lgrpc++ -lprotobuf + $ ./test + Interface Info: + { + "frr-interface:lib": { + "interface": [ + { + "name": "lo", + "vrf": "default", + "state": { + "if-index": 1, + "mtu": 0, + "mtu6": 65536, + "speed": 0, + "metric": 0, + "phy-address": "00:00:00:00:00:00" + }, + "frr-zebra:zebra": { + "state": { + "up-count": 0, + "down-count": 0, + "ptm-status": "disabled" + } + } + }, + { + "name": "r1-eth0", + "vrf": "default", + "state": { + "if-index": 2, + "mtu": 1500, + "mtu6": 1500, + "speed": 10000, + "metric": 0, + "phy-address": "02:37:ac:63:59:b9" + }, + "frr-zebra:zebra": { + "state": { + "up-count": 0, + "down-count": 0, + "ptm-status": "disabled" + } + } + } + ] + }, + "frr-zebra:zebra": { + "mcast-rpf-lookup": "mrib-then-urib", + "workqueue-hold-timer": 10, + "zapi-packets": 1000, + "import-kernel-table": { + "distance": 15 + }, + "dplane-queue-limit": 200 + } + } + + + +.. _grpc-python-example: + +Python Example +-------------- + +The next sections will use Python as an example for writing scripts to use the northbound. +.. _grpc-python-generate: + +Generating Python FRR Bindings +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Generating FRR northbound bindings for Python example: + +:: + + # Install python3 virtual environment capability e.g., + sudo apt-get install python3-venv + + # Create a virtual environment for python grpc and activate + python3 -m venv venv-grpc + source venv-grpc/bin/activate + + # Install grpc requirements + pip install grpcio grpcio-tools + + mkdir /tmp/frr-python + cd grpc + + python3 -m grpc_tools.protoc \ + --python_out=/tmp/frr-python \ + --grpc_python_out=/tmp/frr-python \ + -I $(pwd) \ + frr-northbound.proto + +.. _grpc-python-if-sample: + +Using Python To Get Capabilities and Interfaces State +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Below is a sample script to print capabilities and all interfaces Python +discovered. This demostrates the 2 different RPC results one gets from gRPC, +Unary (`GetCapabilities`) and Streaming (`Get`) for the interface state. + +:: + + import grpc + import frr_northbound_pb2 + import frr_northbound_pb2_grpc + + channel = grpc.insecure_channel('localhost:50051') + stub = frr_northbound_pb2_grpc.NorthboundStub(channel) + + # Print Capabilities + request = frr_northbound_pb2.GetCapabilitiesRequest() + response = stub.GetCapabilities(request) + print(response) + + # Print Interface State and Config + request = frr_northbound_pb2.GetRequest() + request.path.append("/frr-interface:lib") + request.type=frr_northbound_pb2.GetRequest.ALL + request.encoding=frr_northbound_pb2.XML + + for r in stub.Get(request): + print(r.data.data) + +The previous script will output something like: + +:: + + frr_version: "7.7-dev-my-manual-build" + rollback_support: true + supported_modules { + name: "frr-filter" + organization: "FRRouting" + revision: "2019-07-04" + } + supported_modules { + name: "frr-interface" + organization: "FRRouting" + revision: "2020-02-05" + } + [...] + supported_encodings: JSON + supported_encodings: XML + + <lib xmlns="http://frrouting.org/yang/interface"> + <interface> + <name>lo</name> + <vrf>default</vrf> + <state> + <if-index>1</if-index> + <mtu>0</mtu> + <mtu6>65536</mtu6> + <speed>0</speed> + <metric>0</metric> + <phy-address>00:00:00:00:00:00</phy-address> + </state> + <zebra xmlns="http://frrouting.org/yang/zebra"> + <state> + <up-count>0</up-count> + <down-count>0</down-count> + </state> + </zebra> + </interface> + <interface> + <name>r1-eth0</name> + <vrf>default</vrf> + <state> + <if-index>2</if-index> + <mtu>1500</mtu> + <mtu6>1500</mtu6> + <speed>10000</speed> + <metric>0</metric> + <phy-address>f2:62:2e:f3:4c:e4</phy-address> + </state> + <zebra xmlns="http://frrouting.org/yang/zebra"> + <state> + <up-count>0</up-count> + <down-count>0</down-count> + </state> + </zebra> + </interface> + </lib> + +.. _grpc-ruby-example: + +Ruby Example +------------ + +Next sections will use Ruby as an example for writing scripts to use +the northbound. .. _grpc-ruby-generate: Generating Ruby FRR Bindings ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Generating FRR northbound bindings for Ruby example: @@ -52,7 +326,7 @@ Generating FRR northbound bindings for Ruby example: .. _grpc-ruby-if-sample: Using Ruby To Get Interfaces State ----------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Here is a sample script to print all interfaces FRR discovered: @@ -141,7 +415,7 @@ The previous script will output something like this: .. _grpc-ruby-bfd-profile-sample: Using Ruby To Create BFD Profiles ---------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this example you'll learn how to edit configuration using JSON and programmatic (XPath) format. diff --git a/doc/developer/topotests.rst b/doc/developer/topotests.rst index a86566dbb0..dd797a6949 100644 --- a/doc/developer/topotests.rst +++ b/doc/developer/topotests.rst @@ -59,7 +59,7 @@ there are some errors in the upstream MIBS which need to be patched up. The following steps will get you there on Ubuntu 20.04. .. code:: shell - + apt install libsnmp-dev apt install snmpd snmp apt install snmp-mibs-downloader @@ -68,9 +68,9 @@ following steps will get you there on Ubuntu 20.04. wget http://pastebin.com/raw.php?i=p3QyuXzZ -O /usr/share/snmp/mibs/ietf/SNMPv2-PDU wget http://pastebin.com/raw.php?i=gG7j8nyk -O /usr/share/snmp/mibs/ietf/IPATM-IPMC-MIB edit /etc/snmp/snmp.conf to look like this - # As the snmp packages come without MIB files due to license reasons, loading - # of MIBs is disabled by default. If you added the MIBs you can reenable - # loading them by commenting out the following line. + # As the snmp packages come without MIB files due to license reasons, loading + # of MIBs is disabled by default. If you added the MIBs you can reenable + # loading them by commenting out the following line. mibs +ALL @@ -485,7 +485,7 @@ Some things to keep in mind: in BGP, the test should look for the peers reconverging instead of just sleeping an arbitrary amount of time and continuing on. It is ok to use sleep in a tight loop with appropriate show commands to ensure that - the protocol reaches the desired state. This should be bounded by + the protocol reaches the desired state. This should be bounded by appropriate timeouts for the protocol in question though. See verify_bgp_convergence as a good example of this. If you are having troubles figuring out what to look for, please do not be afraid to ask. @@ -882,6 +882,8 @@ Example: Requirements: +- Directory name for a new topotest must not contain hyphen (``-``) characters. + To separate words, use underscores (``_``). For example, `tests/topotests/bgp_new_example`. - Test code should always be declared inside functions that begin with the ``test_`` prefix. Functions beginning with different prefixes will not be run by pytest. diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst index b4ddec10c9..58b9c36e01 100644 --- a/doc/developer/workflow.rst +++ b/doc/developer/workflow.rst @@ -1247,7 +1247,6 @@ the command :clicmd:`show pony` would be documented as follows: .. code-block:: rest - .. index:: show pony .. clicmd:: show pony Prints an ASCII pony. Example output::: |