# Create NAT and routing for Zephyr native network on Linux

This page describes how you can set up a networking rules that allows you to run Zephyr applications
build to native_posix or QEMU targets and get them to access public Internet.



![Network overview](nat.png)

Zephyr applications, when build on native_posix or various qemu targets,
run simulated Ethernet driver that attaches itself to a network interface called zeth.
This is Linux TAP interface so it can send and receive Ethernet frames.

In order to have networking with Zephyr, you need to configure IP address on linux kernel side,
set up the routing and have NAT (Network Address Translation / IP masquerading) for outbound
traffic.

Optionally, having dnsmasq to serve as small stand-alone DHCP and DNS server helps.
When running dnsmasq, it must bind into the zeth interface, so it does not serve any
requests coming from outside network.

## Building the Zephyr application for native networking

At minimun, you need following Kconfig settings for your *native_posix* application to have
working network

```
# General network requirements
CONFIG_NETWORKING=y
CONFIG_NET_IPV4=y
CONFIG_NET_TCP=y
CONFIG_NET_UDP=y
CONFIG_NET_SOCKETS=y

# Native posix requirements
CONFIG_ENTROPY_GENERATOR=y
CONFIG_TEST_RANDOM_GENERATOR=y

CONFIG_NET_L2_ETHERNET=y
CONFIG_ETH_NATIVE_POSIX=y
CONFIG_ETH_NATIVE_POSIX_RANDOM_MAC=y

# IPv4 config
CONFIG_NET_CONFIG_SETTINGS=y
CONFIG_NET_CONFIG_NEED_IPV4=y
CONFIG_NET_CONFIG_MY_IPV4_ADDR="192.0.2.1"
CONFIG_NET_CONFIG_MY_IPV4_GW="192.0.2.2"
CONFIG_DNS_RESOLVER=y
CONFIG_DNS_RESOLVER_MAX_SERVERS=1
CONFIG_DNS_SERVER_IP_ADDRESSES=y
CONFIG_DNS_SERVER1="192.0.2.2"
```

## Running the native_posix app

You can test your configuration for example in `zephyr/samples/net/sockets/http_get` by creating
a file called `boards/native_posix.conf` with the content from the sample above.

```sh
cd zephyr/samples/net/sockets/http_get
# create boards/native_posix.conf

# Building the application
west build -b native_posix -- -DOVERLAY_CONFIG=overlay-tls.conf

# Run the application
# Note that you need to run it realtime (-rt) so responses don't timeout,
# otherwise it would run faster.
# Also any TLS/DTLS traffic needs proper seed or random generator,
# $RANDOM is adequate enough for testing purposes, not secure though,
./build/zephyr/zephyr.elf -rt -seed=$RANDOM

# Run application that use shell, for example lwm2m_client
# These spawn the shell and logs into a virtual serial port on /dev/pts/X
# it is easier to open a x-terminal to this serial port when you start the application
./build/zephyr/zephyr.elf -rt -seed=$RANDOM -attach_uart
```

You might need to supply also `-attach_uart_cmd` parameter, in case default X-terminal is not
installed. For example `-attach_uart_cmd='x-terminal-emulator -e screen %s &'` works.

# Testing with net-tools and Docker

* Create Docker image

	cd docker/
	docker build -t net-tools .

* Setup network interfaces, IP addresses and routes

	sudo ./net-setup.sh --config docker.conf start

* Run Docker image

  Set the docker internal network name to the value $DOCKER_USER_INTERFACE
  in docker.config above, default is 'net-tools0'. The bridge network that
  docker creates will be printed on standard out, it's bridge interface
  name will be br-XXXXXXXXXXXX. Check that the IPv4 and IPv6 addresses
  given on the docker command line match the subnets in 'docker.conf'.

  Interactively:

	docker run --hostname=zephyr --name=net-tools \
	       --ip=192.0.2.2 --ip6=2001:db8::2 \
	       --rm -it --network=net-tools0 net-tools sh

        exit with Ctrl-p ctrl-q to execute tests from the command line

  Non-interactively

	docker run --hostname=zephyr --name=net-tools \
	       --ip=192.0.2.2 --ip6=2001:db8::2 \
	       --rm -dt --network=net-tools0 net-tools sh

* Run Qemu / native-posix image

	rm -rf build && mkdir build

	cmake -GNinja -DBOARD=native_posix -B build
	   or
	cmake -GNinja -DBOARD=qemu_x86 -DOVERLAY_CONFIG=overlay-e1000.conf \
	   -B build

	ninja -C build run

* Execute tests like echo-client

	docker container exec net-tools /net-tools/echo-client 2001:db8::1
	docker container exec net-tools /net-tools/echo-client -t 2001:db8::1
	docker container exec net-tools /net-tools/echo-client 192.0.2.1
	docker container exec net-tools /net-tools/echo-client -t 192.0.2.1

* Remove the network setup:

	sudo ./net-setup.sh --config docker.conf stop

The comments and instructions below are for legacy IP stack in Zephyr.

tunslip6
========

tunslip6 can be used in host side to create a tun device that
is connected to a unix socket that qemu is providing. This
way it is possible to pass packets between host and target
system via slip protocol.

You need to connect tunslip6 to the second qemu serial line
through a UNIX socket (qemu option -serial unix:/tmp/slip-socket).

1) Start socat

$ socat PTY,link=/tmp/slip.dev UNIX-LISTEN:/tmp/slip.sock

2) Start qemu, use the listener demo app. Note that you need to
   set CONFIG_NETWORKING_UART=y in your configuration.

   You might need to set the platform and ARCH like this if simple_uart
   driver is not found in your default platform.

$ make PLATFORM_CONFIG=basic_cortex_m3 ARCH=arm \
     QEMU_EXTRA_FLAGS="-serial none -serial unix:/tmp/slip.sock" qemu

  or just simply

$ make qemu

3) Start tunslip6

$ sudo ./tunslip6 -s `readlink /tmp/slip.dev` 2001:db8::1/64

4) Send data to listener

$ nc -u -6 2001:db8::2 4242 <<EOF
foobar
EOF

There are also convenience scripts for running socat, radvd and
tunslip6 processes called loop-socat.sh, loop-radvd.sh and
loop-slip.sh. So to simplify things you need three terminals
for doing this:

Terminal 1:
$ ./loop-socat.sh

Terminal 2:
$ sudo ./loop-slip.sh

Terminal 3:
$ sudo ./loop-radvd.sh

After running these scripts you do not need to manual restart
them when qemu process stops.


radvd
=====
In order the IPv6 stateless address auto configuration (SLAAC)
to work, you need to run radvd or similar tool in host side.
There is an example radvd.conf file present in the tools directory.

$ sudo radvd -d 1 -C radvd.conf -m stderr


tunslip
=======

tunslip if for IPv4 networks and it can be used in host side
to create a tun device that is connected to a unix socket that
qemu is providing. This way it is possible to pass packets
between host and target system via slip protocol.

You need to connect tunslip to the second qemu serial line
through a UNIX socket (qemu option -serial unix:/tmp/slip-socket).

1) Start socat

$ socat PTY,link=/tmp/slip.dev UNIX-LISTEN:/tmp/slip.sock

2) Start qemu, use the listener demo app. Note that you need to
   set CONFIG_NETWORKING_UART=y in your configuration.

   You might need to set the platform and ARCH like this if simple_uart
   driver is not found in your default platform.

$ make PLATFORM_CONFIG=basic_cortex_m3 ARCH=arm \
     QEMU_EXTRA_FLAGS="-serial none -serial unix:/tmp/slip.sock" qemu

3) Start tunslip

$ sudo ./tunslip -s `readlink /tmp/slip.dev` 192.0.2.1 255.255.255.0

4) Send data to listener

$ nc -u 192.0.2.2 4242 <<EOF
foobar
EOF


echo-client
===========

echo-client is a tool that is run in Linux host side and
which sends pre-defined UDP data packets to echo-server
application that is running in qemu side. This client
process verifies that it is able to receive data correctly
from the echo-server and thus verify that the upper layer
networking components in Zephyr IP stack work properly.

You needs to setup the slip connection (see the steps 1 to 3)
in tunslip6 section of this document.

Example:

$ ./echo-client 2001:db8::2

In order to send multicast IPv6 packets, one needs to
give the network interface as a parameter.

$ ./echo-client -i tun0 ff84::2


echo-server
===========

echo-server is a tool that is run in Linux host side and
which waits UDP data sent by echo-client application that
is running in qemu side.

You needs to setup the slip connection (see the steps 1 to 3)
in tunslip6 section of this document. Make sure that the Linux
host firewall is not blocking the packets that the echo-client
running in qemu is sending via tun0 device.

Example:

$ sudo ./echo-server -i tun0


dtls-client
===========

dtls-client is a tool that is run in Linux host side and
which connects to dtls-server running in qemu.

You needs to setup the slip connection (see the steps 1 to 3)
in tunslip6 section of this document.

Example:

$ make dtls-client

$ ./dtls-client -b 2001:db8::1 2001:db8::2


dtls-server
===========

dtls-server is a tool that is run in Linux host side and
which waits DTLS data sent by dtls-client application that
is running in qemu side.

You needs to setup the slip connection (see the steps 1 to 3)
in tunslip6 section of this document.

Example:

$ make dtls-server

$ ./dtls-server -i tun0

monitor_15_4
============

monitor_15_4 is a tool that is run in Linux host side and
which reads data from pipes which is written buy 15.4 test
application from qemu. This is T juntion tool which reads
and writes data from pipes and feed into pipes (this way
both qemus communicate each other) and same time data
written in PCAP format for wireshark monitoring.

Please also read samples/network/test_15_4/README for
how to configure and run two qemus.

Make and run this tool

$ make

Usage : monitor_15_4 <sample pcap file> [<pipe_1> <pipe_2>]

$ monitor_15_4 sample.pcap

or

$ monitor_15_4 sample.pcap /tmp/ip-15-4-1 /tmp/ip-15-4-2


coap-client
===========

coap-client is a tool that is run in Linux host side and
which connects to coap-server running in qemu.

You needs to setup the slip connection (see the steps 1 to 3)
in tunslip6 section of this document.

Example:

$ make coap-client

If you want to use DTLS then run client like this
$ sudo ./coap-client -i tun0 2001:db8::2

For non-DTLS case, run client like this
$ sudo ./coap-client -n -i tun0 2001:db8::2


coap-observe-client
===================

You can test the coap-observe-client that is running in qemu
using the coap-server example server that is found in libcoap.
So get libcoap package which can be found here
https://github.com/obgm/libcoap.git
Compile and install the libcoap library in host.

You needs to setup the slip connection (see the steps 1 to 3)
in tunslip6 section of this document.

$ /home/user/libcoap/examples/coap-server -A 2001:db8::1 -p 5683

Then in the samples/network/coap_observe_client directory, say

$ make qemu

[![Run Status](https://api.shippable.com/projects/58ffb2b81fb3ec0700e1602f/badge?branch=master)](https://app.shippable.com/github/zephyrproject-rtos/net-tools)

# Networking Tools

The comments and instructions below are for the new IP stack in Zephyr.

In a Zephyr default setup, the network tools are pre-installed under the
`tools` directory.

Here are instructions how to communicate between Zephyr that is running
inside QEMU, and host device that is running Linux.

For setting up routing and NAT rules to allow access to external networks, please see
the [README NAT.md](README%20NAT.md)

You need to run *socat* and *tunslip* to create a minimally working
network setup.

There are convenience scripts (_loop-socat.sh_ and _loop-slip-tap.sh_) for
running socat and tunslip6 processes. For running these, you need two
terminals.

Terminal 1:
```
$ ./loop-socat.sh
```

Terminal 2:
```
$ sudo ./loop-slip-tap.sh
```

After running these scripts you do not need to manually restart
them when qemu process stops.

In the Qemu side, you need to compile the kernel with proper config.
Minimally you need these settings active in your project config file.
```
CONFIG_NETWORKING=y
CONFIG_NET_IPV6=y
CONFIG_NET_IPV4=y
CONFIG_NET_YAIP=y
CONFIG_NET_UDP=y
CONFIG_NET_LOG=y
CONFIG_NET_SLIP=y
CONFIG_SLIP_TAP=y
CONFIG_SYS_LOG=y
CONFIG_SYS_LOG_SHOW_COLOR=y
CONFIG_NANO_TIMEOUTS=y
CONFIG_TEST_RANDOM_GENERATOR=y
```

After you have the loop scripts and Qemu running running you can communicate
with the Zephyr.

If your have echo-server running in the Qemu, then you can use the echo-client
tool in net-tools directory to communicate with it.
```
# ./echo-client -i tap0 2001:db8::1
```
The IP stack responds to ping requests if properly configured.
```
$ ping6 -I tap0 -c 1 2001:db8::1
```
You can attach wireshark to tap0 interface to see what data is being
transferred.

If building with CONFIG_NET_TCP=y in your project config file, it's possible
to run the echo-server sample in Zephyr, and then test the TCP stack using
the supplied tcptest.py script:
```
$ ./tcptest.py tap0 2001:db8::1
```
This script will send numbers to the echo-server program, read them back,
and compare if it got the exact bytes back.  Transmission errors, timeouts,
and time to get the response are all recorded and printed to the standard
output.

Be sure to use Python 3, as it requires a function from the socket module
that's only available in this version (wrapper around if_nametoindex(3)).


## Using net-setup.sh script to setup host side ethernet interface

The net-setup.sh script can setup an ethernet interface to the host.
User is able to setup a configuration file that will contain
commands to setup IP addresses and routes to the host interface.
This net-setup.sh script will need to be run as a root user.

If no parameters are given, then "zeth" network interface and "zeth.conf"
configuration file are used. The script waits until user presses CTRL-c
and then removes the network interface.
```
$ net-setup.sh
```
```
$ net-setup.sh --config zeth-vlan.conf
```
```
$ net-setup.sh --config my-own-config.conf --iface foobar
```

It is also possible to let the script return and then stop the network
interface later. Is can be done by first creating the interface with
"start" or "up" command, and then later remove the interface with
"stop" or "down" command.
```
$ net-setup.sh start
do your things here
$ net-setup.sh stop
```
```
$ net-setup.sh --config my-own-config.conf up
do your things here
$ net-setup.sh --config my-own-config.conf down
```

Any extra parameters that the script does not know, are passed directly
to "ip" command.
```
$ net-setup.sh --config my-own-config.conf --iface foo user bar
```

## Using encrypted SSL link with echo-* programs

Install stunnel

Fedora:
```
$ dnf install stunnel
```
Ubuntu:
```
$ apt-get install stunnel4 -y
```
Finally run the stunnel script in Linux
```
$ ./stunnel.sh
```
And connect echo-client to this SSL tunnel (note that the IP address
is the address of Linux host where the tunnel end point is located).
```
$ ./echo-client -p 4243 2001:db8::2 -t
```
If you are running echo-client in Zephyr QEMU, then run echo-server like
this:
```
$ ./echo-server -p 4244 -i tap0
```

If you want to re-create the certificates in echo-server and echo-client in
Zephyr net samples, then they can be created like this (note that you do not
need to do this as the certs have been prepared already in echo-server and
echo-client sample sources):
```
$ openssl genrsa -out echo-apps-key.pem 2048
$ openssl req -new -x509 -key echo-apps-key.pem -out echo-apps-cert.pem \
    -days 10000 -subj '/CN=localhost'
```
The cert that is to be embedded into test_certs.h in echo-server and
echo-client, can be generated like this:
```
$ openssl x509 -in echo-apps-cert.pem -outform DER | \
    hexdump -e '8/1 "0x%02x, " "\n"' | sed 's/0x  ,//g'
```
The private key to be embedded into test_certs.h in echo-server can be
generated like this:
```
$ openssl pkcs8 -topk8 -inform PEM -outform DER -nocrypt \
    -in echo-apps-key.pem | hexdump -e '8/1 "0x%02x, " "\n"' | \
    sed 's/0x  ,//g'
```

If you want to re-create the signed certificates in echo-server in Zephyr
net samples and echo-client in net-tools, then they can be created like this
(note that you do not need to do this as the certs have been prepared already
in echo-server and echo-client sources):
```
CA
--
$ openssl genrsa -out ca_privkey.pem 2048
$ openssl req -new -x509 -days 36500 -key ca_privkey.pem -out ca.crt -subj "/CN=exampleCA"

Convert to DER format
$ openssl x509 -in ca.crt -outform DER -out ca.der
```

```
Client
------
$ openssl genrsa -out client_privkey.pem 2048
$ openssl req -new -key client_privkey.pem -out client.csr -subj "/CN=exampleClient"
$ openssl x509 -req -CA ca.crt -CAkey ca_privkey.pem -days 36500 -in client.csr -CAcreateserial -out client.crt
```

```
Server
------
$ openssl genrsa -out server_privkey.pem 2048
$ openssl req -new -key server_privkey.pem -out server.csr -subj "/CN=localhost"
$ openssl x509 -req -CA ca.crt -CAkey ca_privkey.pem -days 36500 -in server.csr -CAcreateserial -out server.crt

Convert to DER format
$ openssl x509 -in server.crt -outform DER -out server.der
$ openssl pkcs8 -topk8 -inform PEM -outform DER -nocrypt -in server_privkey.pem -out server_privkey.der
```

Copy ca.crt, client.crt and client_privkey.pem to net-tools.
Copy ca.der, server.der and server_privkey.der to samples/net/sockets/echo-server/src/.

Enable NET_SAMPLE_CERTS_WITH_SC in samples/net/sockets/echo-server and build the sample.
Use stunnel_sc.conf in stunnel.sh to run echo-client with signed certificates.

## Using DTLS link with echo-* programs

For DTLS client functionality, you can do this

```
$ ./dtls-client -c echo-apps-cert.pem 2001:db8::1
```
or
```
$ ./dtls-client -c echo-apps-cert.pem 192.0.2.1
```
For DTLS server functionality, you can do this

```
$ ./dtls-server
```

## TLS connecitivity errors

If you see this error print in zephyr console

[net/app] [ERR] _net_app_ssl_mainloop: Closing connection -0x7180 (SSL - Verification of the message MAC failed)

Then increasing the mbedtls heap size might help. So you can set the option
CONFIG_MBEDTLS_HEAP_SIZE to some higher value.

Example:
```
CONFIG_MBEDTLS_HEAP_SIZE=30000
```

## PPP Connectivity

You can test the PPP connectivity running in Qemu in Zephyr using pppd that is
running in Linux host. You need to run *socat* and *pppd* to create
a minimally working network setup.

There are convenience scripts (_loop-ppp-dev.sh_ and _loop-pppd.sh_) for
running socat and pppd processes. For running these, you need two
terminals.

Terminal 1:
```
$ ./loop-ppp-dev.sh
```

Terminal 2:
```
$ sudo ./loop-pppd.sh
```

After this, start PPP enabled Zephyr application. For example Zephyr
*echo-server* sample in samples/net/sockets/echo_server has _overlay-ppp.conf_
file that enables PPP support.