Re: [Qemu-devel] [PATCH] qemu-doc: Rework the network options chapter to make "-net" less prominent

[Eric Blake]

On 03/09/2018 12:13 AM, Thomas Huth wrote:
> "-net" is clearly a legacy option. Yet we still use it in almost all
> examples in the qemu documentation, and many other spots in the network
> chapter. We should make it less prominent that users are not lured into
> using it so often anymore. So instead of starting the network chapter with
> "-net nic" and documenting "-net <backend>" below "-netdev <backend>"
> everywhere, all the "-net" related documentation is now moved to the end
> of the chapter. The new "--nic" option is moved to the beginning of the
> chapter instead, with a new example that should demonstrate how "--nic"
> can be used to shortcut "--device" with "--netdev".
> And the examples in this chapter are changed to use the "--device" and
> "--netdev" options or "--nic" instead of "-net nic -net <backend>".
>
> Signed-off-by: Thomas Huth <address@hidden>
> ---
>   qemu-options.hx | 210 ++++++++++++++++++++++++++++----------------------------
>   1 file changed, 105 insertions(+), 105 deletions(-)

> address@hidden -netdev user,address@hidden,@var{option}][,@var{option}][,...]
> address@hidden -netdev
> address@hidden -net user[,@var{option}][,@var{option}][,...]
> -Use the user mode network stack which requires no administrator
> address@hidden --nic 
> [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
> +
> +This option is a shortcut for configuring both, the on-board (default) guest

s/both,/both/

> +NIC hardware and the host network backend in one go. The host backend options
> +are the same as with the corresponding @option{--netdev} options below.
> +The guest NIC model can be set with @address@hidden
> +Use @option{model=help} to list the available device types.
> +The hardware MAC address can be set with @address@hidden
> +
> +The following two example do exactly the same, to show how @option{--nic} can
> +be used to shorten the command line length (note that the e1000 is the default
> +on i386, so the @option{model=e1000} parameter could even be omitted here, 
> too):
> address@hidden
> +qemu-system-i386 --netdev user,id=n1,ipv6=off 
> --device=e1000,netdev=n1,mac=52:54:98:76:54:32
> +qemu-system-i386 --nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
> address@hidden example

Nice example.

> +
> address@hidden --nic none
> +Indicate that no network devices should be configured. It is used to override
> +the default configuration (default NIC with @option{--net user} backend) which
> +is activated if no other networking options are provided.
> +
> address@hidden --netdev user,address@hidden,@var{option}][,@var{option}][,...]
> address@hidden --netdev
> +Configure user mode host network backend which requires no administrator
>   privilege to run. Valid options are:
> @@ -2166,8 +2166,6 @@ or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows 
> NT/2000).
>   Then @address@hidden can be accessed in @file{\\smbserver\qemu}.
>   
>   Note that a SAMBA server must be installed on the host OS.
> -QEMU was tested successfully with smbd versions from Red Hat 9,
> -Fedora Core 3 and OpenSUSE 11.x.
>   

This change makes sense, but is somewhat unrelated to -net.  Worth 
splitting the patch?

>   @item hostfwd=[tcp|udp]:address@hidden:@address@hidden:@var{guestport}
>   Redirect incoming TCP or UDP connections to the host port @var{hostport} to
> @@ -2182,7 +2180,7 @@ screen 0, use the following:
>   
>   @example
>   # on the host
> -qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
> +qemu-system-i386 --nic user,hostfwd=tcp:127.0.0.1:6001-:6000

The trailing [...] makes sense here, why did you drop it?

>   # this host xterm should open in the guest X11 server
>   xterm -display :1
>   @end example
> @@ -2192,7 +2190,7 @@ the guest, use the following:
>   
>   @example
>   # on the host
> -qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...]
> +qemu-system-i386 --device e1000,netdev=n1 --netdev 
> user,id=n1,hostfwd=tcp::5555-:23

and again.

Is it worth trying to use backslash-newline in long example lines, or 
are we okay with long lengths?

>   telnet localhost 5555
>   @end example
>   
> @@ -2211,7 +2209,7 @@ lifetime, like in the following example:
>   @example
>   # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
>   # the guest accesses it
> -qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...]
> +qemu-system-i386 --nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
>   @end example

Again, the [...] seems like it is worth keeping.

>   
>   Or you can execute a command on every TCP connection established by the guest,
> @@ -2220,7 +2218,8 @@ so that QEMU behaves similar to an inetd process for that 
> virtual server:
>   @example
>   # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
>   # and connect the TCP stream to its stdin/stdout
> -qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
> +qemu-system-i386 --device e1000,netdev=n1 \
> +  --netdev 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'

Ah, here you DID use a line break in a long example.


> address@hidden -netdev 
> socket,address@hidden,address@hidden,address@hidden:@var{port}[,address@hidden
> address@hidden -net 
> socket[,address@hidden,address@hidden,address@hidden,address@hidden:@var{port}[,address@hidden
> address@hidden --netdev 
> socket,address@hidden,address@hidden,address@hidden:@var{port}[,address@hidden
>   
> -Create a VLAN @var{n} shared with another QEMU virtual
> -machines using a UDP multicast socket, effectively making a bus for
> -every QEMU with same multicast address @var{maddr} and @var{port}.
> +Configure a socket host network backend to shared the guest's network traffic

s/shared/share/

> +with another QEMU virtual machines using a UDP multicast socket, effectively
> +making a bus for every QEMU with same multicast address @var{maddr} and 
> @var{port}.

> +
> address@hidden -net 
> nic[,address@hidden,address@hidden,address@hidden,address@hidden 
> [,address@hidden,address@hidden,address@hidden

Worth spelling this --net instead of -net?

> address@hidden -net

We can have multiple @findex listings; should we list both @findex -net 
and @findex --net?

> +Legacy option to configure or create an on-board (or machine default) Network
> +Interface Card(NIC) and connect it either to the emulated hub port ("vlan")
> +with number @var{n} (@var{n} = 0 is the default), or to the netdev @var{nd}.
> +The NIC is an e1000 by default on the PC target. Optionally, the MAC address
> +can be changed to @var{mac}, the device address set to @var{addr} (PCI cards
> +only), and a @var{name} can be assigned for use in monitor commands.
> +Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
> +that the card should have; this option currently only affects virtio cards; set
> address@hidden = 0 to disable MSI-X. If no @option{-net} option is specified, a 
> single
> +NIC is created.  QEMU can emulate several different models of network card.
> +Use @code{-net nic,model=help} for a list of available devices for your target.
> +
> address@hidden -net 
> user|tap|bridge|socket|l2tpv3|vde[,...][,address@hidden,address@hidden
> +Configure a host network backend (with the options corresponding to the same
> address@hidden option) and connect it to the emulated hub ("vlan") with the
> +number @var{n} (default is number 0). Use @var{name} to specify the name of the
> +hub port.
>   ETEXI
>   
>   STEXI

--
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org