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