README.rst
1.. _sockets-http-client-sample:
2
3Socket HTTP Client
4##################
5
6Overview
7********
8
9This sample application implements an HTTP(S) client that will do an HTTP
10or HTTPS request and wait for the response from the HTTP server.
11
12The source code for this sample application can be found at:
13:zephyr_file:`samples/net/sockets/http_client`.
14
15Requirements
16************
17
18- :ref:`networking_with_host`
19
20Building and Running
21********************
22
23You can use this application on a supported board, including
24running it inside QEMU as described in :ref:`networking_with_qemu`.
25
26Build the http-client sample application like this:
27
28.. zephyr-app-commands::
29 :zephyr-app: samples/net/sockets/http_client
30 :board: <board to use>
31 :conf: <config file to use>
32 :goals: build
33 :compact:
34
35Enabling TLS support
36====================
37
38Enable TLS support in the sample by building the project with the
39``overlay-tls.conf`` overlay file enabled using these commands:
40
41.. zephyr-app-commands::
42 :zephyr-app: samples/net/sockets/http_client
43 :board: qemu_x86
44 :conf: "prj.conf overlay-tls.conf"
45 :goals: build
46 :compact:
47
48An alternative way is to specify ``-DEXTRA_CONF_FILE=overlay-tls.conf`` when
49running ``west build`` or ``cmake``.
50
51The certificate and private key used by the sample can be found in the sample's
52:zephyr_file:`samples/net/sockets/http_client/src/` directory.
53The default certificates used by Socket HTTP Client and
54``https-server.py`` program found in the
55`net-tools <https://github.com/zephyrproject-rtos/net-tools>`_ project, enable
56establishing a secure connection between the samples.
57
58
59Running http-server in Linux Host
60=================================
61
62You can run this ``http-client`` sample application in QEMU
63and run the ``http-server.py`` (from net-tools) on a Linux host.
64
65To use QEMU for testing, follow the :ref:`networking_with_qemu` guide.
66
67In a terminal window:
68
69.. code-block:: console
70
71 $ ./http-server.py
72
73Run ``http-client`` application in QEMU:
74
75.. zephyr-app-commands::
76 :zephyr-app: samples/net/sockets/http_client
77 :host-os: unix
78 :board: qemu_x86
79 :conf: prj.conf
80 :goals: run
81 :compact:
82
83Note that ``http-server.py`` must be running in the Linux host terminal window
84before you start the http-client application in QEMU.
85Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`.
86
87You can verify TLS communication with a Linux host as well. Just use the
88``https-server.py`` program in net-tools project.
89
