1.. zephyr:code-sample:: sockets-big-http-download
2   :name: Large HTTP download
3   :relevant-api: bsd_sockets tls_credentials
4
5   Download a large file from a web server using BSD sockets.
6
7Overview
8********
9
10The sockets/big_http_download sample application for Zephyr implements
11a simple HTTP GET client using a BSD Sockets compatible API. Unlike
12the :zephyr:code-sample:`sockets-http-get` sample application, it downloads a file of
13several megabytes in size, and verifies its integrity using hashing. It
14also performs download repeatedly, tracking the total number of bytes
15transferred. Thus, it can serve as a "load testing" application for
16the Zephyr IP stack.
17
18The source code for this sample application can be found at:
19:zephyr_file:`samples/net/sockets/big_http_download`.
20
21Requirements
22************
23
24- :ref:`networking_with_host`
25- or, a board with hardware networking
26- NAT/routing should be set up to allow connections to the Internet
27- DNS server should be available on the host to resolve domain names
28
29Building and Running
30********************
31
32Build the Zephyr version of the application like this:
33
34.. zephyr-app-commands::
35   :zephyr-app: samples/net/sockets/big_http_download
36   :board: <board_to_use>
37   :goals: build
38   :compact:
39
40After the sample starts, it issues an HTTP GET request for
41http://archive.ubuntu.com/ubuntu/dists/xenial/main/installer-amd64/current/images/hd-media/vmlinuz
42This site was selected as providing files of variety of sizes, together
43with various hashes for them, to ease external selection and verification.
44The particular file selected is 6.7MB in size, so it can show how reliably
45Zephyr streams non-trivial amounts of data, while still taking a
46reasonable amount of time to complete. While the file is downloaded, its
47hash is computed (SHA-256 is used in the source code), and an error
48message is printed if it differs from the reference value, as specified
49in the source code. After a short pause, the process repeats (in an
50infinite loop), while the total counter of the bytes received is kept.
51Thus the application can be used to test transfers of much larger amounts
52of traffic over a longer time.
53
54You can edit the source code to issue a request to any other site on
55the Internet (or on the local network, in which case no NAT/routing
56setup is needed).
57
58.. warning::
59
60   If you are doing extensive testing with this sample, please reference
61   a file on a local server or a special-purpose testing server of your own
62   on the Internet.  Using files on archive.ubuntu.com is not recommended for
63   large-scale testing.
64
65Enabling TLS support
66=================================
67
68Enable TLS support in the sample by building the project with the
69``overlay-tls.conf`` overlay file enabled, for example, using these commands:
70
71.. zephyr-app-commands::
72   :zephyr-app: samples/net/sockets/big_http_download
73   :board: qemu_x86
74   :conf: "prj.conf overlay-tls.conf"
75   :goals: build
76   :compact:
77
78An alternative way is to specify ``-DEXTRA_CONF_FILE=overlay-tls.conf`` when
79running ``west build`` or ``cmake``.
80
81The TLS version of this sample downloads a file from
82https://launchpad.net/ubuntu/+archive/primary/+sourcefiles/git/1:2.34.1-1ubuntu1/git_2.34.1.orig.tar.xz
83(6.6MB). The certificates used by the sample are in the sample's ``src``
84directory and are used to access the default website configured in the sample
85for TLS communication (https://launchpad.net) and possible redirects. To access
86a different web page over TLS, you'll need to provide a different certificate
87to authenticate to that server.
88
89Note, that TLS support in the sample depends on non-posix, TLS socket
90functionality. Therefore, it is only possible to run TLS in this sample
91on Zephyr.
92
93Running application on POSIX Host
94=================================
95
96The same application source code can be built for a POSIX system, e.g.
97Linux.
98
99To build:
100
101.. code-block:: console
102
103    $ make -f Makefile.host
104
105To run:
106
107.. code-block:: console
108
109    $ ./big_http_download
110
111The behavior of the application is the same as the Zephyr version.
112