src/plugins/quic/quic_plugin.rst

   1 .. _quic_plugin:
   2 .. _quicly: https://github.com/h2o/quicly
   3
   4 .. toctree::
   5
   6 QUIC HostStack
   7 ==============
   8
   9 The quic plugin provides an `IETF QUIC protocol <https://tools.ietf.org/html/draft-ietf-quic-transport-22>`_ implementation. It is based on
  10 the quicly_ library.
  11
  12 This plugin adds the QUIC protocol to VPP's Host Stack. As a result QUIC is
  13 usable both in internal VPP applications and in external apps.
  14
  15 **Maturity**
  16
  17 - This plugin is under current development: it should mostly work, but has not been thoroughly tested and should not be used in production.
  18 - Only bidirectional streams are supported currently.
  19
  20 Getting started
  21 ---------------
  22
  23 * A common sample setup is with two vpp instances interconnected #twovppinstances
  24 * Ensure your vpp configuration file contains ``session { evt_qs_memfd_seg }``
  25 * Then run ``session enable`` in the debug cli (vppctl)
  26
  27 This plugin can be tested in the following cases.
  28
  29 Internal client
  30 ^^^^^^^^^^^^^^^
  31
  32 This application is a simple command to be run on the debug cli to test connectivity & throughput on QUIC over the debug cli (vppctl). It does not reflect reality and is mostly used for internal tests.
  33
  34 * Run ``test echo server uri quic://1.1.1.1/1234`` on your first instance
  35 * Then ``test echo client uri quic://20.20.1.1/1`` on the second one
  36
  37 Source for the internal client lives in ``src/plugins/hs_apps/echo_client.c``
  38
  39 External client
  40 ^^^^^^^^^^^^^^^
  41
  42 This setup reflects the use case of an app developer using vpp to create a quic client / server. The application is an external binary that connects to VPP via its binary API.
  43
  44 After having setup two interconnected vpps, you can attach the quic_echo binary to each of them.
  45
  46 * The binary can be found in ``./build-root/build-vpp[_debug]-native/vpp/bin/quic_echo``
  47 * To run the client & server use ``quic_echo socket-name /vpp.sock client|server uri quic://1.1.1.1/1234``
  48 * Several options are available to customize the amount of data sent, number of threads, logging and timing.
  49
  50 The behavior of this app when run with ``nclient 2/4`` is two first establish 2 connections with the given peer, and once everything has been opened start opening 4 quic streams, and transmit data. Flow is as follows.
  51
  52 .. image:: /_images/quic_plugin_echo_flow.png
  53
  54 This allows timing of either the whole setup & teardown or specific phases in assessing the protocol's performance
  55
  56 Source for the internal client lives in ``src/plugins/hs_apps/sapi/quic_echo.c``
  57
  58 VCL client
  59 ^^^^^^^^^^
  60
  61 The hoststack exposes a simplified API call the VCL (blocking posix like calls), this API is used by a sample client & server implementation that supports QUIC, TCP and UDP.
  62
  63 * The binaries can be found in ``./build-root/build-vpp[_debug]-native/vpp/bin/``
  64 * Create the VCL conf files ``echo "vcl { api-socket-name /vpp.sock }" | tee /tmp/vcl.conf]``
  65 * For the server ``VCL_CONFIG=/tmp/vcl.conf ; vcl_test_server -p QUIC 1234"``
  66 * For the client ``VCL_CONFIG=/tmp/vcl.conf ; vcl_test_client -p QUIC 1.1.1.1 1234"``
  67
  68 Source for the internal client lives in ``src/plugins/hs_apps/vcl/vcl_test_client.c``
  69
  70 A basic usage is the following client side
  71
  72 .. code-block:: C
  73
  74   #include <vcl/vppcom.h>
  75   int fd = vppcom_session_create (VPPCOM_PROTO_QUIC);
  76   vppcom_session_tls_add_cert (/* args */);
  77   vppcom_session_tls_add_key (/* args */);
  78   vppcom_session_connect (fd, "quic://1.1.1.1/1234"); /* create a quic connection */
  79   int sfd = vppcom_session_create (VPPCOM_PROTO_QUIC);
  80   vppcom_session_stream_connect (sfd, fd); /* open a quic stream on the connection*/
  81   vppcom_session_write (sfd, buf, n);
  82
  83 Server side
  84
  85 .. code-block:: C
  86
  87   #include <vcl/vppcom.h>
  88   int lfd = vppcom_session_create (VPPCOM_PROTO_QUIC);
  89   vppcom_session_tls_add_cert (/* args */);
  90   vppcom_session_tls_add_key (/* args */);
  91   vppcom_session_bind (fd, "quic://1.1.1.1/1234");
  92   vppcom_session_listen (fd);
  93   int fd = vppcom_session_accept (lfd); /* accept quic connection*/
  94   vppcom_session_is_connectable_listener (fd); /* is true */
  95   int sfd = vppcom_session_accept (fd); /* accept quic stream */
  96   vppcom_session_is_connectable_listener (sfd); /* is false */
  97   vppcom_session_read (sfd, buf, n);
  98
  99
 100 Internal Mechanics
 101 ------------------
 102
 103 QUIC constructs are exposed as follows:
 104
 105 - QUIC connections and streams are both regular host stack session, exposed via the API with their 64bits handle.
 106 - QUIC connections can be created and destroyed with regular ``connect`` and ``close`` calls with ``TRANSPORT_PROTO_QUIC``.
 107 - Streams can be opened in a connection by calling ``connect`` again and passing the handle of the connection to which the new stream should belong.
 108 - Streams can be closed with a regular ``close`` call.
 109 - Streams opened by peers can be accepted from the sessions corresponding to QUIC connections.
 110 - Data can ba exchanged by using the regular ``send`` and ``recv`` calls on the stream sessions.
 111
 112 Data structures
 113 ^^^^^^^^^^^^^^^
 114
 115 Quic relies on the hoststack constructs, namely applications, sessions, transport_connections, and app_listeners. When listening on a port with the quic protocol, an external application :
 116
 117 * Attaches to vpp and register an ``application``
 118 * It creates an ``app_listener`` and a ``quic_listen_session``.
 119 * The ``quic_listen_session`` relies on a ``transport_connection`` (``lctx``) to access the underlying ``udp_listen_session`` that will receive packets.
 120 * Upon connection request, we create the same data structure (``quic_session``, ``qctx``, ``udp_session``) and pass a handle to the ``quic_session`` in the accept callback to acknowledge the creation of a quic connection. All further UDP datagrams for the peers at each end of the connection will be exchanged through the ``udp_session``
 121 * Upon receiving a Stream opening request, we create the ``stream_session`` and its transport ``sctx`` and pass the handle to the ``stream_session`` back to the app. Here we don't have any UDP datastructures, as all datagrams are bound to the connection.
 122
 123
 124 Those structures are linked as follows :
 125
 126 .. image:: /_images/quic_plugin_datastructures.png
 127