1.. zephyr:code-sample:: sockets-http-get
2   :name: HTTP GET using plain sockets
3   :relevant-api: bsd_sockets tls_credentials secure_sockets_options
4
5   Implement an HTTP(S) client using plain BSD sockets.
6
7Overview
8********
9
10The sockets/http_get sample application for Zephyr implements a simple
11HTTP GET client using a BSD Sockets compatible API. The purpose of this
12sample is to show how it's possible to develop a sockets application
13portable to both POSIX and Zephyr. As such, it is kept minimal and
14supports only IPv4.
15
16The source code for this sample application can be found at:
17:zephyr_file:`samples/net/sockets/http_get`.
18
19Requirements
20************
21
22- :ref:`networking_with_host`
23- or, a board with hardware networking
24- NAT/routing should be set up to allow connections to the Internet
25- DNS server should be available on the host to resolve domain names
26
27Building and Running
28********************
29
30Build the Zephyr version of the application like this:
31
32.. zephyr-app-commands::
33   :zephyr-app: samples/net/sockets/http_get
34   :board: <board_to_use>
35   :goals: build
36   :compact:
37
38After the sample starts, it issues HTTP GET request to "google.com:80"
39and dumps the response. You can edit the source code to issue a request
40to any other site on the Internet (or on the local network, in which
41case no NAT/routing setup is needed).
42Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`.
43
44Enabling TLS support
45=================================
46
47Enable TLS support in the sample by building the project with the
48``overlay-tls.conf`` overlay file enabled, for example, using these commands:
49
50.. zephyr-app-commands::
51   :zephyr-app: samples/net/sockets/http_get
52   :board: qemu_x86
53   :conf: "prj.conf overlay-tls.conf"
54   :goals: build
55   :compact:
56
57An alternative way is to specify ``-DEXTRA_CONF_FILE=overlay-tls.conf`` when
58running ``west build`` or ``cmake``.
59
60For boards that support TLS offloading (e.g. TI's cc3220sf_launchxl), use
61``overlay-tls-offload.conf`` instead of ``overlay-tls.conf``.
62
63The certificate used by the sample can be found in the sample's ``src``
64directory. The certificate was selected to enable access to the default website
65configured in the sample (https://google.com). To access a different web page
66over TLS, provide an appropriate certificate to authenticate to that web server.
67
68Note, that TLS support in the sample depends on non-posix, TLS socket
69functionality. Therefore, it is only possible to run TLS in this sample
70on Zephyr.
71
72Running application on POSIX Host
73=================================
74
75The same application source code can be built for a POSIX system, e.g.
76Linux. (Note: if you look at the source, you will see that the code is
77the same except the header files are different for Zephyr vs POSIX.)
78
79To build:
80
81.. code-block:: console
82
83    $ make -f Makefile.host
84
85To run:
86
87.. code-block:: console
88
89    $ ./http_get
90
91As can be seen, the behavior of the application is the same as the Zephyr
92version.
93