1[](https://app.shippable.com/github/zephyrproject-rtos/net-tools) 2 3# Networking Tools 4 5The comments and instructions below are for the new IP stack in Zephyr. 6 7Here are instructions how to communicate between Zephyr that is running 8inside QEMU, and host device that is running Linux. 9 10You need to run *socat* and *tunslip* to create a minimally working 11network setup. 12 13There are convenience scripts (_loop-socat.sh_ and _loop-slip-tap.sh_) for 14running socat and tunslip6 processes. For running these, you need two 15terminals. 16 17Terminal 1: 18``` 19$ ./loop-socat.sh 20``` 21 22Terminal 2: 23``` 24$ sudo ./loop-slip-tap.sh 25``` 26 27After running these scripts you do not need to manually restart 28them when qemu process stops. 29 30In the Qemu side, you need to compile the kernel with proper config. 31Minimally you need these settings active in your project config file. 32``` 33CONFIG_NETWORKING=y 34CONFIG_NET_IPV6=y 35CONFIG_NET_IPV4=y 36CONFIG_NET_YAIP=y 37CONFIG_NET_UDP=y 38CONFIG_NET_LOG=y 39CONFIG_NET_SLIP=y 40CONFIG_SLIP_TAP=y 41CONFIG_SYS_LOG=y 42CONFIG_SYS_LOG_SHOW_COLOR=y 43CONFIG_NANO_TIMEOUTS=y 44CONFIG_TEST_RANDOM_GENERATOR=y 45``` 46 47After you have the loop scripts and Qemu running running you can communicate 48with the Zephyr. 49 50If your have echo-server running in the Qemu, then you can use the echo-client 51tool in net-tools directory to communicate with it. 52``` 53# ./echo-client -i tap0 2001:db8::1 54``` 55The IP stack responds to ping requests if properly configured. 56``` 57$ ping6 -I tap0 -c 1 2001:db8::1 58``` 59You can attach wireshark to tap0 interface to see what data is being 60transferred. 61 62If building with CONFIG_NET_TCP=y in your project config file, it's possible 63to run the echo-server sample in Zephyr, and then test the TCP stack using 64the supplied tcptest.py script: 65``` 66$ ./tcptest.py tap0 2001:db8::1 67``` 68This script will send numbers to the echo-server program, read them back, 69and compare if it got the exact bytes back. Transmission errors, timeouts, 70and time to get the response are all recorded and printed to the standard 71output. 72 73Be sure to use Python 3, as it requires a function from the socket module 74that's only available in this version (wrapper around if_nametoindex(3)). 75 76 77## Using net-setup.sh script to setup host side ethernet interface 78 79The net-setup.sh script can setup an ethernet interface to the host. 80User is able to setup a configuration file that will contain 81commands to setup IP addresses and routes to the host interface. 82This net-setup.sh script will need to be run as a root user. 83 84If no parameters are given, then "zeth" network interface and "zeth.conf" 85configuration file are used. The script waits until user presses CTRL-c 86and then removes the network interface. 87``` 88$ net-setup.sh 89``` 90``` 91$ net-setup.sh --config zeth-vlan.conf 92``` 93``` 94$ net-setup.sh --config my-own-config.conf --iface foobar 95``` 96 97It is also possible to let the script return and then stop the network 98interface later. Is can be done by first creating the interface with 99"start" or "up" command, and then later remove the interface with 100"stop" or "down" command. 101``` 102$ net-setup.sh start 103do your things here 104$ net-setup.sh stop 105``` 106``` 107$ net-setup.sh --config my-own-config.conf up 108do your things here 109$ net-setup.sh --config my-own-config.conf down 110``` 111 112Any extra parameters that the script does not know, are passed directly 113to "ip" command. 114``` 115$ net-setup.sh --config my-own-config.conf --iface foo user bar 116``` 117 118## Using encrypted SSL link with echo-* programs 119 120Install stunnel 121 122Fedora: 123``` 124$ dnf install stunnel 125``` 126Ubuntu: 127``` 128$ apt-get install stunnel4 -y 129``` 130Finally run the stunnel script in Linux 131``` 132$ ./stunnel.sh 133``` 134And connect echo-client to this SSL tunnel (note that the IP address 135is the address of Linux host where the tunnel end point is located). 136``` 137$ ./echo-client -p 4243 2001:db8::2 -t 138``` 139If you are running echo-client in Zephyr QEMU, then run echo-server like 140this: 141``` 142$ ./echo-server -p 4244 -i tap0 143``` 144 145If you want to re-create the certificates in echo-server and echo-client in 146Zephyr net samples, then they can be created like this (note that you do not 147need to do this as the certs have been prepared already in echo-server and 148echo-client sample sources): 149``` 150$ openssl genrsa -out echo-apps-key.pem 2048 151$ openssl req -new -x509 -key echo-apps-key.pem -out echo-apps-cert.pem \ 152 -days 10000 -subj '/CN=localhost' 153``` 154The cert that is to be embedded into test_certs.h in echo-server and 155echo-client, can be generated like this: 156``` 157$ openssl x509 -in echo-apps-cert.pem -outform DER | \ 158 hexdump -e '8/1 "0x%02x, " "\n"' | sed 's/0x ,//g' 159``` 160The private key to be embedded into test_certs.h in echo-server can be 161generated like this: 162``` 163$ openssl pkcs8 -topk8 -inform PEM -outform DER -nocrypt \ 164 -in echo-apps-key.pem | hexdump -e '8/1 "0x%02x, " "\n"' | \ 165 sed 's/0x ,//g' 166``` 167 168If you want to re-create the signed certificates in echo-server in Zephyr 169net samples and echo-client in net-tools, then they can be created like this 170(note that you do not need to do this as the certs have been prepared already 171in echo-server and echo-client sources): 172``` 173CA 174-- 175$ openssl genrsa -out ca_privkey.pem 2048 176$ openssl req -new -x509 -days 36500 -key ca_privkey.pem -out ca.crt -subj "/CN=exampleCA" 177 178Convert to DER format 179$ openssl x509 -in ca.crt -outform DER -out ca.der 180``` 181 182``` 183Client 184------ 185$ openssl genrsa -out client_privkey.pem 2048 186$ openssl req -new -key client_privkey.pem -out client.csr -subj "/CN=exampleClient" 187$ openssl x509 -req -CA ca.crt -CAkey ca_privkey.pem -days 36500 -in client.csr -CAcreateserial -out client.crt 188``` 189 190``` 191Server 192------ 193$ openssl genrsa -out server_privkey.pem 2048 194$ openssl req -new -key server_privkey.pem -out server.csr -subj "/CN=localhost" 195$ openssl x509 -req -CA ca.crt -CAkey ca_privkey.pem -days 36500 -in server.csr -CAcreateserial -out server.crt 196 197Convert to DER format 198$ openssl x509 -in server.crt -outform DER -out server.der 199$ openssl pkcs8 -topk8 -inform PEM -outform DER -nocrypt -in server_privkey.pem -out server_privkey.der 200``` 201 202Copy ca.crt, client.crt and client_privkey.pem to net-tools. 203Copy ca.der, server.der and server_privkey.der to samples/net/sockets/echo-server/src/. 204 205Enable NET_SAMPLE_CERTS_WITH_SC in samples/net/sockets/echo-server and build the sample. 206Use stunnel_sc.conf in stunnel.sh to run echo-client with signed certificates. 207 208## Using DTLS link with echo-* programs 209 210For DTLS client functionality, you can do this 211 212``` 213$ ./dtls-client -c echo-apps-cert.pem 2001:db8::1 214``` 215or 216``` 217$ ./dtls-client -c echo-apps-cert.pem 192.0.2.1 218``` 219For DTLS server functionality, you can do this 220 221``` 222$ ./dtls-server 223``` 224 225## TLS connecitivity errors 226 227If you see this error print in zephyr console 228 229[net/app] [ERR] _net_app_ssl_mainloop: Closing connection -0x7180 (SSL - Verification of the message MAC failed) 230 231Then increasing the mbedtls heap size might help. So you can set the option 232CONFIG_MBEDTLS_HEAP_SIZE to some higher value. 233 234Example: 235``` 236CONFIG_MBEDTLS_HEAP_SIZE=30000 237``` 238 239## PPP Connectivity 240 241You can test the PPP connectivity running in Qemu in Zephyr using pppd that is 242running in Linux host. You need to run *socat* and *pppd* to create 243a minimally working network setup. 244 245There are convenience scripts (_loop-ppp-dev.sh_ and _loop-pppd.sh_) for 246running socat and pppd processes. For running these, you need two 247terminals. 248 249Terminal 1: 250``` 251$ ./loop-ppp-dev.sh 252``` 253 254Terminal 2: 255``` 256$ sudo ./loop-pppd.sh 257``` 258 259After this, start PPP enabled Zephyr application. For example Zephyr 260*echo-server* sample in samples/net/sockets/echo_server has _overlay-ppp.conf_ 261file that enables PPP support. 262
