[Qemu-devel] [PATCH v2] qemu-options: add documentation for using UDP unicast network backend.

[Qemu-devel] [PATCH v2] qemu-options: add documentation for using UDP unicast network backend.

[Victor Kaplansky]

For the long time QEMU has support for UDP unicast network
backend added by commit 0e0e7facc775e9, but manual was missing
description and usage examples.

Changes from v1:

    Address comments by Michael S. Tsirkin:
      - remove superfluous empty lines.
      - place the note about two QEMU instances after the example.
      - English and others cleanups.

Signed-off-by: Victor Kaplansky <victork@redhat.com>
---
 qemu-options.hx | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/qemu-options.hx b/qemu-options.hx
index 2485b94..6bdb884 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1907,6 +1907,28 @@ qemu-system-i386 linux.img \
                  -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
 @end example
 
+@item -netdev socket,id=@var{id}[,fd=@var{h}][,udp=@var{rhost}:@var{rport}[,localaddr=@var{lhost}:@var{lport}]]
+@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,udp=@var{rhost}:@var{rport}[,localaddr=@var{rhost}:@var{lport}]]
+
+Connect a VLAN @var{n} to a remote VLAN in another QEMU virtual
+machine using a UDP tunnel. Use lhost:lport as the local host and
+port, rhost:rport as the remote host and port of the tunnel.  Use
+@option{fd=h} to specify an already opened UDP socket.
+
+Example:
+@example
+# launch one QEMU instance
+qemu-system-i386 linux.img \
+                 -device virtio-net-pci,netdev=net0 \
+                 -netdev socket,id=net0,udp=localhost:4444,localaddr=localhost:5555
+# launch a second QEMU instance sharing the network with the first one
+qemu-system-i386 linux.img \
+                 -device virtio-net-pci,netdev=net0 \
+                 -netdev socket,id=net0,udp=localhost:5555,localaddr=localhost:4444
+
+NOTE: The two QEMU instances can be running on different hosts.
+@end example
+
 @item -netdev l2tpv3,id=@var{id},src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}]
 @itemx -net l2tpv3[,vlan=@var{n}][,name=@var{name}],src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}]
 Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular
-- 
--Victor

Re: [Qemu-devel] [PATCH v2] qemu-options: add documentation for using UDP unicast network backend.

[Michael S. Tsirkin]

On Mon, Oct 19, 2015 at 03:13:44PM +0300, Victor Kaplansky wrote:
> For the long time QEMU has support for UDP unicast network
> backend added by commit 0e0e7facc775e9, but manual was missing
> description and usage examples.
> 
> Changes from v1:
> 
>     Address comments by Michael S. Tsirkin:
>       - remove superfluous empty lines.
>       - place the note about two QEMU instances after the example.
>       - English and others cleanups.

This text should come after ---: this way git am will skip
it when applying the patch.
Whoever's applying this can probably take it out so
I think this is not a reason to repost.

> Signed-off-by: Victor Kaplansky <victork@redhat.com>
> ---
>  qemu-options.hx | 22 ++++++++++++++++++++++
>  1 file changed, 22 insertions(+)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 2485b94..6bdb884 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1907,6 +1907,28 @@ qemu-system-i386 linux.img \
>                   -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
>  @end example
>  
> +@item -netdev socket,id=@var{id}[,fd=@var{h}][,udp=@var{rhost}:@var{rport}[,localaddr=@var{lhost}:@var{lport}]]
> +@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,udp=@var{rhost}:@var{rport}[,localaddr=@var{rhost}:@var{lport}]]
> +
> +Connect a VLAN @var{n} to a remote VLAN in another QEMU virtual
> +machine using a UDP tunnel.


I thought about this, and I wonder how does this work wrt MTU discovery
(when not using localhost). Does guest have to reduce MTU to make packets fit?
QEMU doesn't enable fragmentation or report issues to guest.

Probably worth documenting. Maybe suggest looking at udp(7) for some
work-arounds.

> Use lhost:lport as the local host and
> +port,

BTW 0.0.0.0 is a local value for lhost, isn't it?
Address is just passed on to bind, and that's INADDR_ANY so I think it's
supposed to work, but I didn't try.
If yes, it might be worth documenting.

> rhost:rport as the remote host and port of the tunnel.  Use
> +@option{fd=h} to specify an already opened UDP socket.
> +
> +Example:
> +@example
> +# launch one QEMU instance
> +qemu-system-i386 linux.img \
> +                 -device virtio-net-pci,netdev=net0 \
> +                 -netdev socket,id=net0,udp=localhost:4444,localaddr=localhost:5555
> +# launch a second QEMU instance sharing the network with the first one
> +qemu-system-i386 linux.img \
> +                 -device virtio-net-pci,netdev=net0 \
> +                 -netdev socket,id=net0,udp=localhost:5555,localaddr=localhost:4444
> +
> +NOTE: The two QEMU instances can be running on different hosts.
> +@end example
> +
>  @item -netdev l2tpv3,id=@var{id},src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}]
>  @itemx -net l2tpv3[,vlan=@var{n}][,name=@var{name}],src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}]
>  Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular
> -- 
> --Victor