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

[Thomas Huth]

On 12.03.2018 13:20, 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". The examples in this
> chapter are changed to use the "-device" and "-netdev" options or
> "-nic" instead of "-net nic -net <backend>".
> 
> While we're at it, also remove a legacy remark about very old Linux
> distributions. Also remove the "[...]" from the examples in this chapter
> since we are not using this ellipsis in any other examples in our docu-
> mentation.
> 
> Signed-off-by: Thomas Huth <address@hidden>
> ---
>  v3:
>  - Use single dash options instead of double-dash options
> 
>  qemu-options.hx | 189 
> ++++++++++++++++++++++++++++----------------------------
>  1 file changed, 94 insertions(+), 95 deletions(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 6585058..e86b3fb 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -2045,41 +2045,40 @@ DEF("net", HAS_ARG, QEMU_OPTION_net,
>      "                old way to initialize a host network interface\n"
>      "                (use the -netdev option if possible instead)\n", 
> QEMU_ARCH_ALL)
>  STEXI
> address@hidden -net 
> nic[,address@hidden,address@hidden,address@hidden,address@hidden 
> [,address@hidden,address@hidden,address@hidden
> address@hidden -net
> -Configure or create an on-board (or machine default) Network Interface Card
> -(NIC) and connect it either to VLAN @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.
> -Valid values for @var{type} are
> address@hidden, @code{i82551}, @code{i82557b}, @code{i82559er},
> address@hidden, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
> address@hidden, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
> -Not all devices are supported on all targets.  Use @code{-net nic,model=help}
> -for a list of available devices for your target.
> address@hidden -nic 
> [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
> address@hidden -nic
> +This option is a shortcut for configuring both the on-board (default) guest
> +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
> +
> address@hidden -nic none
> +Indicate that no network devices should be configured. It is used to override
> +the default configuration (default NIC with ``user'' host network backend)
> +which is activated if no other networking options are provided.
>  
>  @item -netdev user,address@hidden,@var{option}][,@var{option}][,...]
>  @findex -netdev
> address@hidden -net user[,@var{option}][,@var{option}][,...]
> -Use the user mode network stack which requires no administrator
> +Configure user mode host network backend which requires no administrator
>  privilege to run. Valid options are:
>  
>  @table @option
> address@hidden address@hidden
> -Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
> -
>  @item address@hidden
> address@hidden address@hidden
>  Assign symbolic name for use in monitor commands.
>  
> address@hidden and @option{ipv6} specify that either IPv4 or IPv6 must
> -be enabled.  If neither is specified both protocols are enabled.
> address@hidden ipv4=on|off and ipv6=on|off
> +Specify that either IPv4 or IPv6 must be enabled. If neither is specified
> +both protocols are enabled.
>  
>  @item address@hidden/@var{mask}]
>  Set IP network address the guest will see. Optionally specify the netmask,
> @@ -2131,7 +2130,7 @@ can not be resolved.
>  
>  Example:
>  @example
> -qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...]
> +qemu-system-i386 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
>  @end example
>  
>  @item address@hidden
> @@ -2147,7 +2146,8 @@ a guest from a local directory.
>  
>  Example (using pxelinux):
>  @example
> -qemu-system-i386 -hda linux.img -boot n -net 
> user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
> +qemu-system-i386 -hda linux.img -boot n -device e1000,netdev=n1 \
> +    -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
>  @end example
>  
>  @item address@hidden,address@hidden
> @@ -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.
>  
>  @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
>  # 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 -nic user,hostfwd=tcp::5555-:23
>  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
>  
>  Or you can execute a command on every TCP connection established by the 
> guest,
> @@ -2220,7 +2218,7 @@ 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 -nic  'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 
> 10.10.1.1 4321'
>  @end example
>  
>  @end table
> @@ -2231,8 +2229,7 @@ syntax gives undefined results. Their use for new 
> applications is discouraged
>  as they will be removed from future versions.
>  
>  @item -netdev 
> tap,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden
> address@hidden -net 
> tap[,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden
> -Connect the host TAP network interface @var{name} to VLAN @var{n}.
> +Configure a host TAP network backend with ID @var{id}.
>  
>  Use the network script @var{file} to configure it and the network script
>  @var{dfile} to deconfigure it. If @var{name} is not provided, the OS
> @@ -2253,7 +2250,7 @@ Examples:
>  
>  @example
>  #launch a QEMU instance with the default network script
> -qemu-system-i386 linux.img -net nic -net tap
> +qemu-system-i386 linux.img -nic tap
>  @end example
>  
>  @example
> @@ -2267,12 +2264,11 @@ qemu-system-i386 linux.img \
>  @example
>  #launch a QEMU instance with the default network helper to
>  #connect a TAP device to bridge br0
> -qemu-system-i386 linux.img \
> -                 -net nic -net tap,"helper=/path/to/qemu-bridge-helper"
> +qemu-system-i386 linux.img -device virtio-net-pci,netdev=n1 \
> +        -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
>  @end example
>  
>  @item -netdev bridge,address@hidden,address@hidden,address@hidden
> address@hidden -net 
> bridge[,address@hidden,address@hidden,address@hidden,address@hidden
>  Connect a host TAP network interface to a host bridge device.
>  
>  Use the network helper @var{helper} to configure the TAP interface and
> @@ -2285,21 +2281,20 @@ Examples:
>  @example
>  #launch a QEMU instance with the default network helper to
>  #connect a TAP device to bridge br0
> -qemu-system-i386 linux.img -net bridge -net nic,model=virtio
> +qemu-system-i386 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
>  @end example
>  
>  @example
>  #launch a QEMU instance with the default network helper to
>  #connect a TAP device to bridge qemubr0
> -qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio
> +qemu-system-i386 linux.img -netdev bridge,br=qemubr0,id=n1 -device 
> virtio-net,netdev=n1
>  @end example
>  
>  @item -netdev 
> socket,address@hidden,address@hidden,address@hidden:@var{port}][,address@hidden:@var{port}]
> address@hidden -net socket[,address@hidden,address@hidden,address@hidden 
> [,address@hidden:@var{port}][,address@hidden:@var{port}]
>  
> -Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
> -machine using a TCP socket connection. If @option{listen} is
> -specified, QEMU waits for incoming connections on @var{port}
> +This host network backend can be used to connect the guest's network to
> +another QEMU virtual machine using a TCP socket connection. If 
> @option{listen}
> +is specified, QEMU waits for incoming connections on @var{port}
>  (@var{host} is optional). @option{connect} is used to connect to
>  another QEMU instance using the @option{listen} option. @address@hidden
>  specifies an already opened TCP socket.
> @@ -2308,21 +2303,19 @@ Example:
>  @example
>  # launch a first QEMU instance
>  qemu-system-i386 linux.img \
> -                 -net nic,macaddr=52:54:00:12:34:56 \
> -                 -net socket,listen=:1234
> -# connect the VLAN 0 of this instance to the VLAN 0
> -# of the first instance
> +                 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
> +                 -netdev socket,id=n1,listen=:1234
> +# connect the network of this instance to the network of the first instance
>  qemu-system-i386 linux.img \
> -                 -net nic,macaddr=52:54:00:12:34:57 \
> -                 -net socket,connect=127.0.0.1:1234
> +                 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
> +                 -netdev socket,id=n2,connect=127.0.0.1:1234
>  @end example
>  
>  @item -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
>  
> -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 share the guest's network traffic
> +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}.
>  NOTES:
>  @enumerate
>  @item
> @@ -2339,25 +2332,24 @@ Example:
>  @example
>  # launch one QEMU instance
>  qemu-system-i386 linux.img \
> -                 -net nic,macaddr=52:54:00:12:34:56 \
> -                 -net socket,mcast=230.0.0.1:1234
> +                 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
> +                 -netdev socket,id=n1,mcast=230.0.0.1:1234
>  # launch another QEMU instance on same "bus"
>  qemu-system-i386 linux.img \
> -                 -net nic,macaddr=52:54:00:12:34:57 \
> -                 -net socket,mcast=230.0.0.1:1234
> +                 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
> +                 -netdev socket,id=n2,mcast=230.0.0.1:1234
>  # launch yet another QEMU instance on same "bus"
>  qemu-system-i386 linux.img \
> -                 -net nic,macaddr=52:54:00:12:34:58 \
> -                 -net socket,mcast=230.0.0.1:1234
> +                 -device e1000,netdev=n3,macaddr=52:54:00:12:34:58 \
> +                 -netdev socket,id=n3,mcast=230.0.0.1:1234
>  @end example
>  
>  Example (User Mode Linux compat.):
>  @example
> -# launch QEMU instance (note mcast address selected
> -# is UML's default)
> +# launch QEMU instance (note mcast address selected is UML's default)
>  qemu-system-i386 linux.img \
> -                 -net nic,macaddr=52:54:00:12:34:56 \
> -                 -net socket,mcast=239.192.168.1:1102
> +                 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
> +                 -netdev socket,id=n1,mcast=239.192.168.1:1102
>  # launch UML
>  /path/to/linux ubd0=/path/to/root_fs eth0=mcast
>  @end example
> @@ -2365,14 +2357,13 @@ qemu-system-i386 linux.img \
>  Example (send packets from host's 1.2.3.4):
>  @example
>  qemu-system-i386 linux.img \
> -                 -net nic,macaddr=52:54:00:12:34:56 \
> -                 -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
> +                 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
> +                 -netdev 
> socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
>  @end example
>  
>  @item -netdev 
> l2tpv3,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden,ipv6][,udp][,cookie64][,counter][,pincounter][,address@hidden,address@hidden,address@hidden
> address@hidden -net 
> l2tpv3[,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden,ipv6][,udp][,cookie64][,counter][,pincounter][,address@hidden,address@hidden,address@hidden
> -Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular
> -protocol to transport Ethernet (and other Layer 2) data frames between
> +Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a
> +popular protocol to transport Ethernet (and other Layer 2) data frames 
> between
>  two systems. It is present in routers, firewalls and the Linux kernel
>  (from version 3.3 onwards).
>  
> @@ -2425,14 +2416,13 @@ brctl addif br-lan vmtunnel0
>  # on 4.3.2.1
>  # launch QEMU instance - if your network has reorder or is very lossy add 
> ,pincounter
>  
> -qemu-system-i386 linux.img -net nic -net 
> l2tpv3,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
> -
> +qemu-system-i386 linux.img -device e1000,netdev=n1 \
> +    -netdev 
> l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
>  
>  @end example
>  
>  @item -netdev 
> vde,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden
> address@hidden -net vde[,address@hidden,address@hidden,address@hidden 
> [,address@hidden,address@hidden,address@hidden
> -Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
> +Configure VDE backend to connect to PORT @var{n} of a vde switch running on 
> host and
>  listening for incoming connections on @var{socketpath}. Use GROUP 
> @var{groupname}
>  and MODE @var{octalmode} to change default ownership and permissions for
>  communication port. This option is only available if QEMU has been compiled
> @@ -2443,19 +2433,9 @@ Example:
>  # launch vde switch
>  vde_switch -F -sock /tmp/myswitch
>  # launch QEMU instance
> -qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
> +qemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch
>  @end example
>  
> address@hidden -netdev hubport,address@hidden,address@hidden,address@hidden
> -
> -Create a hub port on QEMU "vlan" @var{hubid}.
> -
> -The hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a 
> single
> -netdev.  @code{-net} and @code{-device} with parameter @option{vlan} create 
> the
> -required hub automatically. Alternatively, you can also connect the hubport
> -to another netdev with ID @var{nd} by using the @address@hidden
> -option.
> -
>  @item -netdev vhost-user,address@hidden,vhostforce=on|off][,queues=n]
>  
>  Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev 
> should
> @@ -2474,17 +2454,36 @@ qemu -m 512 -object 
> memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,sha
>       -device virtio-net-pci,netdev=net0
>  @end example
>  
> address@hidden --nic 
> [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr]
> address@hidden -netdev hubport,address@hidden,address@hidden,address@hidden
>  
> -This option is a shortcut for setting both, the on-board (default) guest NIC
> -hardware and the host network backend in one go. The host backend options are
> -the same as with the corresponding @option{--netdev} option. The guest NIC
> -hardware MAC address can be set with @address@hidden
> +Create a hub port on the emulated hub with ID @var{hubid}.
>  
> 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.
> +The hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a
> +single netdev. @code{-net} and @code{-device} with the parameter 
> @option{vlan}
> +(deprecated), or @code{-nic hubport} can also be used to connect a
> +network device or a NIC to a hub. Alternatively, you can also connect the
> +hubport to another netdev with ID @var{nd} by using the @address@hidden
> +option.
> +
> address@hidden -net 
> nic[,address@hidden,address@hidden,address@hidden,address@hidden 
> [,address@hidden,address@hidden,address@hidden
> address@hidden -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

Ping!

Any chance that we could still update the documentation for QEMU 2.12?

 Thomas