1.. _networking_with_native_sim:
2
3Networking with native_sim board
4################################
5
6.. contents::
7    :local:
8    :depth: 2
9
10Using virtual/TAP Ethernet driver
11*********************************
12
13This paragraph describes how to set up a virtual network between a (Linux) host
14and a Zephyr application running in a :ref:`native_sim <native_sim>` board.
15
16In this example, the :zephyr:code-sample:`sockets-echo-server` sample application from
17the Zephyr source distribution is run in native_sim board. The Zephyr
18native_sim board instance is connected to a Linux host using a tuntap device
19which is modeled in Linux as an Ethernet network interface.
20
21Prerequisites
22=============
23
24On the Linux Host, fetch the Zephyr ``net-tools`` project, which is located
25in a separate Git repository:
26
27.. code-block:: console
28
29   git clone https://github.com/zephyrproject-rtos/net-tools
30
31
32Basic Setup
33===========
34
35For the steps below, you will need three terminal windows:
36
37* Terminal #1 is terminal window with net-tools being the current
38  directory (``cd net-tools``)
39* Terminal #2 is your usual Zephyr development terminal,
40  with the Zephyr environment initialized.
41* Terminal #3 is the console to the running Zephyr native_sim
42  instance (optional).
43
44Step 1 - Create Ethernet interface
45----------------------------------
46
47Before starting native_sim with network emulation, a network interface
48should be created.
49
50In terminal #1, type:
51
52.. code-block:: console
53
54   ./net-setup.sh
55
56You can tweak the behavior of the net-setup.sh script. See various options
57by running ``net-setup.sh`` like this:
58
59.. code-block:: console
60
61   ./net-setup.sh --help
62
63
64Step 2 - Start app in native_sim board
65--------------------------------------
66
67Build and start the ``echo_server`` sample application.
68
69In terminal #2, type:
70
71.. zephyr-app-commands::
72   :zephyr-app: samples/net/sockets/echo_server
73   :host-os: unix
74   :board: native_sim
75   :goals: run
76   :compact:
77
78
79Step 3 - Connect to console (optional)
80--------------------------------------
81
82The console window should be launched automatically when the Zephyr instance is
83started but if it does not show up, you can manually connect to the console.
84The native_sim board will print a string like this when it starts:
85
86.. code-block:: console
87
88   UART connected to pseudotty: /dev/pts/5
89
90You can manually connect to it like this:
91
92.. code-block:: console
93
94   screen /dev/pts/5
95
96Using offloaded sockets
97***********************
98
99The main advantage over `Using virtual/TAP Ethernet driver`_ is not needing to
100setup a virtual network interface on the host machine. This means that no
101leveraged (root) privileges are needed.
102
103Step 1 - Start app in native_sim board
104======================================
105
106Build and start the ``echo_server`` sample application:
107
108.. zephyr-app-commands::
109   :zephyr-app: samples/net/sockets/echo_server
110   :host-os: unix
111   :board: native_sim
112   :gen-args: -DEXTRA_CONF_FILE=overlay-nsos.conf
113   :goals: run
114   :compact:
115
116Step 2 - run echo-client from net-tools
117=======================================
118
119On the Linux Host, fetch the Zephyr ``net-tools`` project, which is located
120in a separate Git repository:
121
122.. code-block:: console
123
124   git clone https://github.com/zephyrproject-rtos/net-tools
125
126.. note::
127
128   Native Simulator with the offloaded sockets network driver is using the same
129   network interface/namespace as any other (Linux) application that uses BSD
130   sockets API. This means that :zephyr:code-sample:`sockets-echo-server` and
131   ``echo-client`` applications will communicate over localhost/loopback
132   interface (address ``127.0.0.1``).
133
134To run UDP test, type:
135
136.. code-block:: console
137
138   ./echo-client 127.0.0.1
139
140For TCP test, type:
141
142.. code-block:: console
143
144   ./echo-client -t 127.0.0.1
145
146Setting interface name from command line
147****************************************
148
149By default the Ethernet interface name used by native_sim is determined by
150:kconfig:option:`CONFIG_ETH_NATIVE_POSIX_DRV_NAME`, but is also possible
151to set it from the command line using ``--eth-if=<interface_name>``.
152This can be useful if the application has to be
153run in multiple instances and recompiling it for each instance would be
154troublesome.
155
156.. code-block:: console
157
158   ./zephyr.exe --eth-if=zeth2
159