README.rst
1.. zephyr:code-sample:: sockets-http-client
2 :name: HTTP Client
3 :relevant-api: bsd_sockets http_client tls_credentials secure_sockets_options
4
5 Implement an HTTP(S) client that issues a variety of HTTP requests.
6
7Overview
8********
9
10This sample application implements an HTTP(S) client that will do an HTTP
11or HTTPS request and wait for the response from the HTTP server.
12
13The source code for this sample application can be found at:
14:zephyr_file:`samples/net/sockets/http_client`.
15
16Requirements
17************
18
19- :ref:`networking_with_host`
20
21Building and Running
22********************
23
24You can use this application on a supported board, including
25running it inside QEMU as described in :ref:`networking_with_qemu`.
26
27Build the http-client sample application like this:
28
29.. zephyr-app-commands::
30 :zephyr-app: samples/net/sockets/http_client
31 :board: <board to use>
32 :conf: <config file to use>
33 :goals: build
34 :compact:
35
36Enabling TLS support
37====================
38
39Enable TLS support in the sample by building the project with the
40``overlay-tls.conf`` overlay file enabled using these commands:
41
42.. zephyr-app-commands::
43 :zephyr-app: samples/net/sockets/http_client
44 :board: qemu_x86
45 :conf: "prj.conf overlay-tls.conf"
46 :goals: build
47 :compact:
48
49An alternative way is to specify ``-DEXTRA_CONF_FILE=overlay-tls.conf`` when
50running ``west build`` or ``cmake``.
51
52The certificate and private key used by the sample can be found in the sample's
53:zephyr_file:`samples/net/sockets/http_client/src/` directory.
54The default certificates used by Socket HTTP Client and ``https-server.py``
55program found in the `net-tools`_ project, enable establishing a secure
56connection 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
90.. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools
91
