1.. _networking_with_multiple_instances:
2
3Networking with multiple Zephyr instances
4#########################################
5
6.. contents::
7    :local:
8    :depth: 2
9
10This page describes how to set up a virtual network between multiple
11Zephyr instances. The Zephyr instances could be running inside QEMU
12or could be native_sim board processes. The Linux host can be used
13to route network traffic between these systems.
14
15Prerequisites
16*************
17
18On the Linux Host, find the Zephyr `net-tools`_ project, which can either be
19found in a Zephyr standard installation under the ``tools/net-tools`` directory
20or installed stand alone from its own git repository:
21
22.. code-block:: console
23
24   git clone https://github.com/zephyrproject-rtos/net-tools
25
26Basic Setup
27***********
28
29For the steps below, you will need five terminal windows:
30
31* Terminal #1 and #2 are terminal windows with net-tools being the current
32  directory (``cd net-tools``)
33* Terminal #3, where you setup bridging in Linux host
34* Terminal #4 and #5 are your usual Zephyr development terminal,
35  with the Zephyr environment initialized.
36
37As there are multiple ways to setup the Zephyr network, the example below uses
38``qemu_x86`` board with ``e1000`` Ethernet controller and native_sim board
39to simplify the setup instructions. You can use other QEMU boards and drivers
40if needed, see :ref:`networking_with_eth_qemu` for details. You can also use
41two or more native_sim board Zephyr instances and connect them together.
42
43
44Step 1 - Create configuration files
45===================================
46
47Before starting QEMU with network connectivity, a network interfaces for each
48Zephyr instance should be created in the host system. The default setup for
49creating network interface cannot be used here as that is for connecting one
50Zephyr instance to Linux host.
51
52For Zephyr instance #1, create file called ``zephyr1.conf`` to ``net-tools``
53project, or to some other suitable directory.
54
55.. code-block:: console
56
57   # Configuration file for setting IP addresses for a network interface.
58   INTERFACE="$1"
59   HWADDR="00:00:5e:00:53:11"
60   IPV6_ADDR_1="2001:db8:100::2"
61   IPV6_ROUTE_1="2001:db8:100::/64"
62   IPV4_ADDR_1="198.51.100.2/24"
63   IPV4_ROUTE_1="198.51.100.0/24"
64   ip link set dev $INTERFACE up
65   ip link set dev $INTERFACE address $HWADDR
66   ip -6 address add $IPV6_ADDR_1 dev $INTERFACE nodad
67   ip -6 route add $IPV6_ROUTE_1 dev $INTERFACE
68   ip address add $IPV4_ADDR_1 dev $INTERFACE
69   ip route add $IPV4_ROUTE_1 dev $INTERFACE > /dev/null 2>&1
70
71For Zephyr instance #2, create file called ``zephyr2.conf`` to ``net-tools``
72project, or to some other suitable directory.
73
74.. code-block:: console
75
76   # Configuration file for setting IP addresses for a network interface.
77   INTERFACE="$1"
78   HWADDR="00:00:5e:00:53:22"
79   IPV6_ADDR_1="2001:db8:200::2"
80   IPV6_ROUTE_1="2001:db8:200::/64"
81   IPV4_ADDR_1="203.0.113.2/24"
82   IPV4_ROUTE_1="203.0.113.0/24"
83   ip link set dev $INTERFACE up
84   ip link set dev $INTERFACE address $HWADDR
85   ip -6 address add $IPV6_ADDR_1 dev $INTERFACE nodad
86   ip -6 route add $IPV6_ROUTE_1 dev $INTERFACE
87   ip address add $IPV4_ADDR_1 dev $INTERFACE
88   ip route add $IPV4_ROUTE_1 dev $INTERFACE > /dev/null 2>&1
89
90
91Step 2 - Create Ethernet interfaces
92===================================
93
94The following ``net-setup.sh`` commands should be typed in net-tools
95directory (``cd net-tools``).
96
97In terminal #1, type:
98
99.. code-block:: console
100
101   ./net-setup.sh -c zephyr1.conf -i zeth.1
102
103In terminal #2, type:
104
105.. code-block:: console
106
107   ./net-setup.sh -c zephyr2.conf -i zeth.2
108
109
110Step 3 - Setup network bridging
111===============================
112
113In terminal #3, type:
114
115.. code-block:: console
116
117   sudo brctl addbr zeth-br
118   sudo brctl addif zeth-br zeth.1
119   sudo brctl addif zeth-br zeth.2
120   sudo ifconfig zeth-br up
121
122
123Step 4 - Start Zephyr instances
124===============================
125
126In this example we start :zephyr:code-sample:`sockets-echo-server` and
127:zephyr:code-sample:`sockets-echo-client` sample applications. You can use other applications
128too as needed.
129
130In terminal #4, if you are using QEMU, type this:
131
132.. code-block:: console
133
134   west build -d build/server -b qemu_x86 -t run \
135      samples/net/sockets/echo_server -- \
136      -DEXTRA_CONF_FILE=overlay-e1000.conf \
137      -DCONFIG_NET_CONFIG_MY_IPV4_ADDR=\"198.51.100.1\" \
138      -DCONFIG_NET_CONFIG_PEER_IPV4_ADDR=\"203.0.113.1\" \
139      -DCONFIG_NET_CONFIG_MY_IPV6_ADDR=\"2001:db8:100::1\" \
140      -DCONFIG_NET_CONFIG_PEER_IPV6_ADDR=\"2001:db8:200::1\" \
141      -DCONFIG_NET_CONFIG_MY_IPV4_GW=\"203.0.113.1\" \
142      -DCONFIG_ETH_QEMU_IFACE_NAME=\"zeth.1\" \
143      -DCONFIG_ETH_QEMU_EXTRA_ARGS=\"mac=00:00:5e:00:53:01\"
144
145or if you want to use native_sim board, type this:
146
147.. code-block:: console
148
149   west build -d build/server -b native_sim -t run \
150      samples/net/sockets/echo_server -- \
151      -DCONFIG_NET_CONFIG_MY_IPV4_ADDR=\"198.51.100.1\" \
152      -DCONFIG_NET_CONFIG_PEER_IPV4_ADDR=\"203.0.113.1\" \
153      -DCONFIG_NET_CONFIG_MY_IPV6_ADDR=\"2001:db8:100::1\" \
154      -DCONFIG_NET_CONFIG_PEER_IPV6_ADDR=\"2001:db8:200::1\" \
155      -DCONFIG_NET_CONFIG_MY_IPV4_GW=\"203.0.113.1\" \
156      -DCONFIG_ETH_NATIVE_POSIX_DRV_NAME=\"zeth.1\" \
157      -DCONFIG_ETH_NATIVE_POSIX_MAC_ADDR=\"00:00:5e:00:53:01\" \
158      -DCONFIG_ETH_NATIVE_POSIX_RANDOM_MAC=n
159
160
161In terminal #5, if you are using QEMU, type this:
162
163.. code-block:: console
164
165   west build -d build/client -b qemu_x86 -t run \
166      samples/net/sockets/echo_client -- \
167      -DEXTRA_CONF_FILE=overlay-e1000.conf \
168      -DCONFIG_NET_CONFIG_MY_IPV4_ADDR=\"203.0.113.1\" \
169      -DCONFIG_NET_CONFIG_PEER_IPV4_ADDR=\"198.51.100.1\" \
170      -DCONFIG_NET_CONFIG_MY_IPV6_ADDR=\"2001:db8:200::1\" \
171      -DCONFIG_NET_CONFIG_PEER_IPV6_ADDR=\"2001:db8:100::1\" \
172      -DCONFIG_NET_CONFIG_MY_IPV4_GW=\"198.51.100.1\" \
173      -DCONFIG_ETH_QEMU_IFACE_NAME=\"zeth.2\" \
174      -DCONFIG_ETH_QEMU_EXTRA_ARGS=\"mac=00:00:5e:00:53:02\"
175
176or if you want to use native_sim board, type this:
177
178.. code-block:: console
179
180   west build -d build/client -b native_sim -t run \
181      samples/net/sockets/echo_client -- \
182      -DCONFIG_NET_CONFIG_MY_IPV4_ADDR=\"203.0.113.1\" \
183      -DCONFIG_NET_CONFIG_PEER_IPV4_ADDR=\"198.51.100.1\" \
184      -DCONFIG_NET_CONFIG_MY_IPV6_ADDR=\"2001:db8:200::1\" \
185      -DCONFIG_NET_CONFIG_PEER_IPV6_ADDR=\"2001:db8:100::1\" \
186      -DCONFIG_NET_CONFIG_MY_IPV4_GW=\"198.51.100.1\" \
187      -DCONFIG_ETH_NATIVE_POSIX_DRV_NAME=\"zeth.2\" \
188      -DCONFIG_ETH_NATIVE_POSIX_MAC_ADDR=\"00:00:5e:00:53:02\" \
189      -DCONFIG_ETH_NATIVE_POSIX_RANDOM_MAC=n
190
191
192Also if you have firewall enabled in your host, you need to allow traffic
193between ``zeth.1``, ``zeth.2`` and ``zeth-br`` interfaces.
194
195.. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools
196