1.. _networking_with_user_qemu:
2
3Networking with QEMU User
4#############################
5
6.. contents::
7    :local:
8    :depth: 2
9
10This page is intended to serve as a starting point for anyone interested in
11using QEMU SLIRP with Zephyr.
12
13Introduction
14*************
15
16SLIRP is a network backend which provides the complete TCP/IP stack within
17QEMU and uses that stack to implement a virtual NAT'd network. As there are
18no dependencies on the host, SLIRP is simple to setup.
19
20By default, QEMU uses the ``10.0.2.X/24`` network and runs a gateway at
21``10.0.2.2``. All traffic intended for the host network has to travel through
22this gateway, which will filter out packets based on the QEMU command line
23parameters. This gateway also functions as a DHCP server for all GOS,
24allowing them to be automatically assigned with an IP address starting from
25``10.0.2.15``.
26
27More details about User Networking can be obtained from here:
28https://wiki.qemu.org/Documentation/Networking#User_Networking_.28SLIRP.29
29
30Using SLIRP with Zephyr
31************************
32
33In order to use SLIRP with Zephyr, the user has to set the Kconfig option to
34enable User Networking.
35
36.. code-block:: console
37
38   CONFIG_NET_QEMU_USER=y
39
40Once this configuration option is enabled, all QEMU launches will use SLIRP.
41In the default configuration, Zephyr only enables User Networking, and does
42not pass any arguments to it. This means that the Guest will only be able to
43communicate to the QEMU gateway, and any data intended for the host machine
44will be dropped by QEMU.
45
46In general, QEMU User Networking can take in a lot of arguments including,
47
48* Information about host/guest port forwarding. This must be provided to
49  create a communication channel between the guest and host.
50* Information about network to use. This may be valuable if the user does
51  not want to use the default ``10.0.2.X`` network.
52* Tell QEMU to start DHCP server at user-defined IP address.
53* ID and other information.
54
55As this information varies with every use case, it is difficult to come up
56with good defaults that work for all. Therefore, Zephyr Implementation
57offloads this to the user, and expects that they will provide arguments
58based on requirements. For this, there is a Kconfig string which can be
59populated by the user.
60
61.. code-block:: console
62
63   CONFIG_NET_QEMU_USER_EXTRA_ARGS="net=192.168.0.0/24,hostfwd=tcp::8080-:8080"
64
65This option is appended as-is to the QEMU command line. Therefore, any problems with
66this command line will be reported by QEMU only. Here's what this particular
67example will do,
68
69* Make QEMU use the ``192.168.0.0/24`` network instead of the default.
70* Enable forwarding of any TCP data received from port 8080 of host to port
71  8080 of guest, and vice versa.
72
73Limitations
74*************
75
76If the user does not have any specific networking requirements other than the
77ability to access a web page from the guest, user networking (slirp) is a
78good choice. However, it has several limitations
79
80* There is a lot of overhead so the performance is poor.
81* The guest is not directly accessible from the host or the external network.
82* In general, ICMP traffic does not work (so you cannot use ping within a guest).
83* As port mappings need to be defined before launching qemu, clients which use
84  dynamically generated ports cannot communicate with external network.
85* There is a bug in the SLIRP implementation which filters out all IPv6 packets
86  from the guest. See https://bugs.launchpad.net/qemu/+bug/1724590 for details.
87  Therefore, IPv6 will not work with User Networking.
88