samples/net/sockets/big_http_download/README.rst

.. _sockets-big-http-download:

Socket Big HTTP Download Example
################################

Overview
********

The sockets/big_http_download sample application for Zephyr implements
a simple HTTP GET client using a BSD Sockets compatible API. Unlike
the :ref:`sockets-http-get` sample application, it downloads a file of
several megabytes in size, and verifies its integrity using hashing. It
also performs download repeatedly, tracking the total number of bytes
transferred. Thus, it can serve as a "load testing" application for
the Zephyr IP stack.

The source code for this sample application can be found at:
:zephyr_file:`samples/net/sockets/big_http_download`.

Requirements
************

- :ref:`networking_with_host`
- or, a board with hardware networking
- NAT/routing should be set up to allow connections to the Internet
- DNS server should be available on the host to resolve domain names

Building and Running
********************

Build the Zephyr version of the application like this:

.. zephyr-app-commands::
   :zephyr-app: samples/net/sockets/big_http_download
   :board: <board_to_use>
   :goals: build
   :compact:

After the sample starts, it issues an HTTP GET request for
http://archive.ubuntu.com/ubuntu/dists/xenial/main/installer-amd64/current/images/hd-media/vmlinuz
This site was selected as providing files of variety of sizes, together
with various hashes for them, to ease external selection and verification.
The particular file selected is 6.7MB in size, so it can show how reliably
Zephyr streams non-trivial amounts of data, while still taking a
reasonable amount of time to complete. While the file is downloaded, its
hash is computed (SHA-256 is used in the source code), and an error
message is printed if it differs from the reference value, as specified
in the source code. After a short pause, the process repeats (in an
infinite loop), while the total counter of the bytes received is kept.
Thus the application can be used to test transfers of much larger amounts
of traffic over a longer time.

You can edit the source code to issue a request to any other site on
the Internet (or on the local network, in which case no NAT/routing
setup is needed).

.. warning::

   If you are doing extensive testing with this sample, please reference
   a file on a local server or a special-purpose testing server of your own
   on the Internet.  Using files on archive.ubuntu.com is not recommended for
   large-scale testing.

Enabling TLS support
=================================

Enable TLS support in the sample by building the project with the
``overlay-tls.conf`` overlay file enabled, for example, using these commands:

.. zephyr-app-commands::
   :zephyr-app: samples/net/sockets/big_http_download
   :board: qemu_x86
   :conf: "prj.conf overlay-tls.conf"
   :goals: build
   :compact:

An alternative way is to specify ``-DOVERLAY_CONFIG=overlay-tls.conf`` when
running ``west build`` or ``cmake``.

The TLS version of this sample downloads a file from
https://www.7-zip.org/a/7z1805.exe (1.1MB). The certificate
used by the sample is in the sample's ``src`` directory and is configured
to access the default website configured in the sample for TLS
communication (https://www.7-zip.org). To access a different
web page over TLS, you'll need to provide a different certificate
to authenticate to that server.

Note, that TLS support in the sample depends on non-posix, TLS socket
functionality. Therefore, it is only possible to run TLS in this sample
on Zephyr.

Running application on POSIX Host
=================================

The same application source code can be built for a POSIX system, e.g.
Linux.

To build for a host POSIX OS:

.. code-block:: console

    $ make -f Makefile.posix

To run:

.. code-block:: console

    $ ./big_http_download

The behavior of the application is the same as the Zephyr version.