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

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

[Victor Kaplansky]

For a long time QEMU has had support for UDP unicast network
backend, but manual was missing description and usage examples.

This patch adds some more documentation and an example.

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

diff --git a/qemu-options.hx b/qemu-options.hx
index 2485b94..342bb14 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1855,6 +1855,8 @@ qemu-system-i386 linux.img \
                  -net socket,connect=127.0.0.1:1234
 @end example
 
+
+
 @item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
 @itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
 
@@ -1907,6 +1909,27 @@ 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{host}:@var{rport}[,localaddr=@var{host}:@var{lport}]]
+
+Connect a VLAN @var{n} to a remote VLAN in another QEMU virtual
+machine using a UDP tunnel. Use lport as local port and rport as
+remote port of the tunnel. The two QEMU can be running on
+different hosts. 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=127.0.0.1:4444,localaddr=127.0.0.1:5555
+# launch 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=127.0.0.1:5555,localaddr=127.0.0.1:4444
+@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] qemu-options: add documentation for using UDP unicast network backend.

[Michael S. Tsirkin]

On Mon, Oct 19, 2015 at 12:49:15PM +0300, Victor Kaplansky wrote:
> For a long time QEMU has had support for UDP unicast network
> backend, but manual was missing description and usage examples.
> 
> This patch adds some more documentation and an example.
> 
> Signed-off-by: Victor Kaplansky <victork@redhat.com>


Good point, thanks!
Minor comments:

> ---
>  qemu-options.hx | 23 +++++++++++++++++++++++
>  1 file changed, 23 insertions(+)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 2485b94..342bb14 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1855,6 +1855,8 @@ qemu-system-i386 linux.img \
>                   -net socket,connect=127.0.0.1:1234
>  @end example
>  
> +
> +
>  @item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
>  @itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
>  

Why add this here? Probably safe to drop.

> @@ -1907,6 +1909,27 @@ 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{host}:@var{rport}[,localaddr=@var{host}:@var{lport}]]

-net variant says "host" -netdev - lhost/rhost.

> +
> +Connect a VLAN @var{n} to a remote VLAN in another QEMU virtual
> +machine using a UDP tunnel. Use lport as local port and rport as
> +remote port of the tunnel.

the local port/the remote port

Pls document lhost/rhost as well.
> The two QEMU 

QEMU instances


>can be running on
> +different hosts.

There are no "the two QEMU" so far.
Should this come after the examples?

> 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=127.0.0.1:4444,localaddr=127.0.0.1:5555
> +# launch second QEMU instance sharing the network with the first one

"a second QEMU instance"

> +qemu-system-i386 linux.img \
> +                 -device virtio-net-pci,netdev=net0 \
> +                 -netdev socket,id=net0,udp=127.0.0.1:5555,localaddr=127.0.0.1:4444

localhost might be a bit clearer, this way people know names are OK to use, too.
It does work, doesn't it?

> +@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