1.. zephyr:code-sample:: sockets-echo-server
2   :name: Echo server (advanced)
3   :relevant-api: bsd_sockets tls_credentials
4
5   Implement a UDP/TCP server that sends received packets back to the sender.
6
7Overview
8********
9
10The echo-server sample application for Zephyr implements a UDP/TCP server
11that complements the echo-client sample application: the echo-server listens
12for incoming IPv4 or IPv6 packets (sent by the echo client) and simply sends
13them back.
14
15The source code for this sample application can be found at:
16:zephyr_file:`samples/net/sockets/echo_server`.
17
18Requirements
19************
20
21- :ref:`networking_with_host`
22
23Building and Running
24********************
25
26There are multiple ways to use this application. One of the most common
27usage scenario is to run echo-server application inside QEMU. This is
28described in :ref:`networking_with_qemu`.
29
30There are configuration files for different boards and setups in the
31echo-server directory:
32
33- :file:`prj.conf`
34  Generic config file, normally you should use this.
35
36- :file:`overlay-ot.conf`
37  This overlay config enables support for OpenThread.
38
39- :file:`overlay-802154.conf`
40  This overlay config enables support for native IEEE 802.15.4 connectivity.
41  Note, that by default IEEE 802.15.4 L2 uses unacknowledged communication. To
42  improve connection reliability, acknowledgments can be enabled with shell
43  command: ``ieee802154 ack set``.
44
45- :file:`overlay-qemu_802154.conf`
46  This overlay config enables support for two QEMU's when simulating
47  IEEE 802.15.4 network that are connected together.
48
49- :file:`overlay-tls.conf`
50  This overlay config enables support for TLS.
51
52- :file:`overlay-tunnel.conf`
53  This overlay config enables support for IP tunneling.
54
55Build echo-server sample application like this:
56
57.. zephyr-app-commands::
58   :zephyr-app: samples/net/sockets/echo_server
59   :board: <board to use>
60   :conf: <config file to use>
61   :goals: build
62   :compact:
63
64Example building for the nrf52840dk/nrf52840 with OpenThread support:
65
66.. zephyr-app-commands::
67   :zephyr-app: samples/net/sockets/echo_server
68   :host-os: unix
69   :board: nrf52840dk/nrf52840
70   :conf: "prj.conf overlay-ot.conf"
71   :goals: run
72   :compact:
73
74Example building for the samr21_xpro with RF2XX driver support:
75
76.. zephyr-app-commands::
77   :zephyr-app: samples/net/sockets/echo_server
78   :host-os: unix
79   :board: [samr21_xpro | sam4e_xpro | sam_v71_xult/samv71q21]
80   :gen-args: -DEXTRA_CONF_FILE=overlay-802154.conf
81   :goals: build flash
82   :compact:
83
84In a terminal window you can check if communication is happen:
85
86.. code-block:: console
87
88    $ minicom -D /dev/ttyACM0
89
90Enabling TLS support
91====================
92
93Enable TLS support in the sample by building the project with the
94``overlay-tls.conf`` overlay file enabled, for example, using these commands:
95
96.. zephyr-app-commands::
97   :zephyr-app: samples/net/sockets/echo_server
98   :board: qemu_x86
99   :conf: "prj.conf overlay-tls.conf"
100   :goals: build
101   :compact:
102
103An alternative way is to specify ``-DEXTRA_CONF_FILE=overlay-tls.conf`` when
104running ``west build`` or ``cmake``.
105
106The certificate used by the sample can be found in the sample's ``src``
107directory. The default certificates used by Socket Echo Server and
108:zephyr:code-sample:`sockets-echo-client` enable establishing a secure connection
109between the samples.
110
111Running echo-client in Linux Host
112=================================
113
114There is one useful testing scenario that can be used with Linux host.
115Here echo-server is run in QEMU and echo-client is run in Linux host.
116
117To use QEMU for testing, follow the :ref:`networking_with_qemu` guide.
118
119Run echo-server application in QEMU:
120
121.. zephyr-app-commands::
122   :zephyr-app: samples/net/sockets/echo_server
123   :host-os: unix
124   :board: qemu_x86
125   :goals: run
126   :compact:
127
128In a terminal window:
129
130.. code-block:: console
131
132    $ sudo ./echo-client -i tap0 2001:db8::1
133
134Note that echo-server must be running in QEMU before you start the
135echo-client application in host terminal window.
136
137You can verify TLS communication with a Linux host as well. See
138https://github.com/zephyrproject-rtos/net-tools documentation for information
139on how to test TLS with Linux host samples.
140
141See the :zephyr:code-sample:`sockets-echo-client` sample documentation for an alternate
142way of running, with the echo-server on the Linux host and the echo-client
143in QEMU.
144