.. _install_sandboxes_udp:

User Datagram Protocol (UDP)
============================

.. sidebar:: Requirements

   .. include:: _include/docker-env-setup-link.rst

   :ref:`curl <start_sandboxes_setup_curl>`
        Used to make HTTP requests.

   :ref:`netcat <start_sandboxes_setup_netcat>`
        Used to send UDP packets.

This sandbox provides a very simple example of Envoy proxying UDP.

It also demonstrates UDP traffic stats provided by the Envoy admin endpoint.

Step 1: Build the sandbox
*************************

Change to the ``udp`` directory.

Start the Docker composition:

.. code-block:: console

  $ pwd
  examples/udp
  $ docker compose pull
  $ docker compose up --build -d
  $ docker compose ps

      Name                 Command                   State      Ports
  -----------------------------------------------------------------------------------------------------------------------
  udp_envoy-udp_1     /docker-entrypoint.sh /usr ... Up     10000/tcp, 0.0.0.0:10000->10000/udp, 0.0.0.0:10001->10001/tcp
  udp_service-udp_1   python -u /udplistener.py      Up     5005/tcp, 5005/udp

Envoy should proxy UDP on port ``10000`` to an upstream server listening on port ``5005``.

Envoy also provides an admin endpoint listening on port ``10001``.

Step 2: Send some UDP messages
******************************

You can use ``netcat`` to send packets to the upstream server, proxied by Envoy:

.. code-block:: console

   echo -n HELO | nc -4u -w1 127.0.0.1 10000
   echo -n OLEH | nc -4u -w1 127.0.0.1 10000

Step 3: Check the logs of the upstream UDP listener server
**********************************************************

Checking the logs of the upstream server you should see the packets that you sent:

.. code-block:: console

   $ docker compose logs service-udp
   Attaching to udp_service-udp_1
   service-udp_1  | Listening on UDP port 5005
   service-udp_1  | HELO
   service-udp_1  | OLEH

Step 4: View the Envoy admin UDP stats
**************************************

You can view the UDP-related stats provided by the Envoy admin endpoint.

For example, to view the non-zero stats:

.. code-block:: console

   $ curl -s http://127.0.0.1:10001/stats | grep udp | grep -v "\: 0"
   cluster.service_udp.default.total_match_count: 1
   cluster.service_udp.max_host_weight: 1
   cluster.service_udp.membership_change: 1
   cluster.service_udp.membership_healthy: 1
   cluster.service_udp.membership_total: 1
   cluster.service_udp.udp.sess_tx_datagrams: 2
   cluster.service_udp.update_attempt: 1
   cluster.service_udp.update_success: 1
   cluster.service_udp.upstream_cx_tx_bytes_total: 8
   udp.service.downstream_sess_active: 2
   udp.service.downstream_sess_rx_bytes: 8
   udp.service.downstream_sess_rx_datagrams: 2
   udp.service.downstream_sess_total: 2
   cluster.service_udp.upstream_cx_connect_ms: No recorded values
   cluster.service_udp.upstream_cx_length_ms: No recorded values