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