1.. zephyr:code-sample:: eth-native-posix
2   :name: Native POSIX Ethernet
3   :relevant-api: net_core ethernet
4
5   Create a network interface to the host system.
6
7Overview
8********
9
10The eth_native_posix sample application for Zephyr creates a **zeth** network
11interface to the host system. One can communicate with Zephyr via this network
12interface.
13
14The source code for this sample application can be found at:
15:zephyr_file:`samples/net/eth_native_posix`.
16
17Building And Running
18********************
19
20To build the eth_native_posix sample application, follow the steps
21below.
22
23.. zephyr-app-commands::
24   :zephyr-app: samples/net/eth_native_posix
25   :host-os: unix
26   :board: native_posix
27   :conf: <config file to use>
28   :goals: build
29   :compact:
30
31Normally one needs extra privileges to create and configure the TAP device in
32the host system. If the user has set the
33:kconfig:option:`CONFIG_ETH_NATIVE_POSIX_STARTUP_AUTOMATIC` option (this is disabled
34by default), then the user needs to use ``sudo`` to execute the Zephyr process
35with admin privileges, like this:
36
37.. code-block:: console
38
39    sudo --preserve-env=ZEPHYR_BASE make -Cbuild run
40
41If the ``sudo --preserve-env=ZEPHYR_BASE`` gives an error,
42just use ``sudo --preserve-env`` instead.
43
44If the :kconfig:option:`CONFIG_ETH_NATIVE_POSIX_STARTUP_AUTOMATIC` option
45is not enabled (this is the default), then the user should
46execute the ``net-setup.sh`` script from Zephyr `net-tools`_ repository.
47The script should be run before executing the Zephyr process. The script
48will create the zeth interface and set up IP addresses and routes.
49While running ``net-setup.sh`` requires root access, afterwards Zephyr
50process can be run as a non-root user.
51
52You can run the ``net-setup.sh`` script like this::
53
54   cd net-tools
55   sudo ./net-setup.sh
56
57or::
58
59   sudo ./net-setup.sh --config ./zeth-vlan.conf
60
61See also other command line options by typing ``net-setup.sh --help``.
62
63When the network interface is set up manually, you can leave the wireshark
64to monitor the interface, and then start and stop the zephyr process without
65stopping the wireshark.
66
67Setting things manually works the same as working with SLIP connectivity
68in QEMU.
69
70If you want to connect two Zephyr instances together, you can do it like this:
71
72Create two Zephyr config files prj1.conf and prj2.conf. You can use
73:zephyr_file:`samples/net/eth_native_posix/prj.conf` as a base.
74
75Set prj1.conf IP address configuration like this:
76
77.. code-block:: console
78
79    CONFIG_NET_CONFIG_MY_IPV6_ADDR="2001:db8:100::1"
80    CONFIG_NET_CONFIG_PEER_IPV6_ADDR="2001:db8:100::2"
81    CONFIG_NET_CONFIG_MY_IPV4_ADDR="198.51.100.1"
82    CONFIG_NET_CONFIG_PEER_IPV4_ADDR="198.51.100.2"
83    CONFIG_NET_CONFIG_MY_IPV4_GW="203.0.113.1"
84    CONFIG_ETH_NATIVE_POSIX_RANDOM_MAC=n
85    CONFIG_ETH_NATIVE_POSIX_MAC_ADDR="00:00:5e:00:53:64"
86    CONFIG_ETH_NATIVE_POSIX_SETUP_SCRIPT="echo"
87    CONFIG_ETH_NATIVE_POSIX_DRV_NAME="zeth.1"
88
89Set prj2.conf IP address configuration like this:
90
91.. code-block:: console
92
93    CONFIG_NET_CONFIG_MY_IPV6_ADDR="2001:db8:200::1"
94    CONFIG_NET_CONFIG_PEER_IPV6_ADDR="2001:db8:200::2"
95    CONFIG_NET_CONFIG_MY_IPV4_ADDR="203.0.113.1"
96    CONFIG_NET_CONFIG_PEER_IPV4_ADDR="203.0.113.2"
97    CONFIG_NET_CONFIG_MY_IPV4_GW="198.51.100.1"
98    CONFIG_ETH_NATIVE_POSIX_RANDOM_MAC=n
99    CONFIG_ETH_NATIVE_POSIX_MAC_ADDR="00:00:5e:00:53:c8"
100    CONFIG_ETH_NATIVE_POSIX_SETUP_SCRIPT="echo"
101    CONFIG_ETH_NATIVE_POSIX_DRV_NAME="zeth.2"
102
103Then compile and run two Zephyr instances
104(if ``sudo --preserve-env=ZEPHYR_BASE`` gives an error,
105just use ``sudo --preserve-env`` instead):
106
107.. code-block:: console
108
109    cmake -DCONF_FILE=prj1.conf -DBOARD=native_posix -Bbuild1/native_posix .
110    make -s -C build1/native_posix
111    sudo --preserve-env=ZEPHYR_BASE make -s -C build1/native_posix run
112
113.. code-block:: console
114
115    cmake -DCONF_FILE=prj2.conf -DBOARD=native_posix -Bbuild2/native_posix .
116    make -s -C build2/native_posix
117    sudo --preserve-env=ZEPHYR_BASE make -s -C build2/native_posix run
118
119Bridge the two Zephyr instances together:
120
121.. code-block:: console
122
123    sudo brctl addbr zeth-br
124    sudo brctl addif zeth-br zeth.1
125    sudo brctl addif zeth-br zeth.2
126    sudo ifconfig zeth-br up
127
128After this, you are able to ping device 1 from device 2 in net-shell:
129
130.. code-block:: console
131
132    # In device 1
133    net ping 2001:db8:200::1
134    net ping 203.0.113.1
135
136.. code-block:: console
137
138    # In device 2
139    net ping 2001:db8:100::1
140    net ping 198.51.100.1
141
142Note that in this setup you cannot access these two Zephyr devices from
143your host. If you want to do that, then you could create a new network
144interface with proper IP addresses and add that interface to the Zephyr
145bridge.
146
147.. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools
148