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

[Thomas Huth <thuth@redhat.com>]

On 09.03.2018 15:36, Eric Blake wrote:
> 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 <thuth@redhat.com>
>> ---
>>   qemu-options.hx | 210
>> ++++++++++++++++++++++++++++----------------------------
>>   1 file changed, 105 insertions(+), 105 deletions(-)
>>
> 
>> -@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
>> -@findex -netdev
>> -@item -net user[,@var{option}][,@var{option}][,...]
>> -Use the user mode network stack which requires no administrator
>> +@item --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 @option{model=@var{modelname}}.
>> +Use @option{model=help} to list the available device types.
>> +The hardware MAC address can be set with @option{mac=@var{macaddr}}.
>> +
>> +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):
>> +@example
>> +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
>> +@end example
> 
> Nice example.

... but looks like I even got it wrong - it should be "--device e1000",
without "=". Will fix it.

>> +
>> +@item --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.
>> +
>> +@item --netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
>> +@findex --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 @file{@var{dir}} 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?

Not sure whether it's really worth the effort ... I think I'll just
mention it in the patch description, ok?

>>   @item
>> hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@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?

Since we're incredibly inconsistent with that. Some examples do have
that "[...]", many others don't have it. Since the amount of examples
without it is larger than the amount of examples with it, I think it's
more consistent to drop it here.

I guess I should mention this in the commit message, too.

>> +@item -net
>> nic[,vlan=@var{n}][,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}]
>> [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
> 
> Worth spelling this --net instead of -net?

Yes, that's more consistent.

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

I think we should finally also use double dashes for all @findex entries
(if the option is longer than just one letter).

 Thomas