Re: [Qemu-devel] [PATCH] rename vlan to vnet and mark vlan as deprecated

["Daniel P. Berrange" <berrange@redhat.com>]

On Tue, Dec 09, 2008 at 04:01:53PM +0100, Gildas wrote:
> -- 
> This patch renames occurences of vlan/VLAN that are not related to IEE
> 802.1q vlans to vnet/VNET respectively.
> 
> Usage of vlan= in the -net options is still allowed but will produce
> an error message on stderr indicating that the option is now
> deprecated and will be removed in the future.

This bit will just piss people off. By all means change t to allow
the net vnet= option, but printing out a warning for vlan= on every
boot is just going to annoy people and they cannot simply change
their scripts because they may well need to run with old QEMU and
new QEMU

> -    vlan_id = 0;
> -    if (get_param_value(buf, sizeof(buf), "vlan", p)) {
> -        vlan_id = strtol(buf, NULL, 0);
> +    vnet_id = 0;
> +    if (get_param_value(buf, sizeof(buf), "vnet", p)) {
> +        vnet_id = strtol(buf, NULL, 0);
>      }
> -    vlan = qemu_find_vlan(vlan_id);
> -    if (!vlan) {
> -        fprintf(stderr, "Could not create vlan %d\n", vlan_id);
> +    /* support for deprecated keyword "vlan" */
> +    if (get_param_value(buf, sizeof(buf), "vlan", p)) {
> +        fprintf(stderr,
> +            "Use of keyword 'vlan' is deprecated and will be removed.");
> +        fprintf(stderr,
> +            " Use the keyword 'vnet' instead\n");

Kill those two fprintf() which will just serve to annoy. We
should merely document  that vnet= is the preferred syntax
but not actually remove vlan=. There is simply too much
documentation out there refering to vlan= to remove it 
completely.

> diff -Naur trunk/qemu-doc.texi local/qemu-doc.texi
> --- trunk/qemu-doc.texi	2008-12-09 13:23:15.000000000 +0100
> +++ local/qemu-doc.texi	2008-12-09 13:38:00.000000000 +0100
> @@ -604,8 +604,8 @@
>  
>  @table @option
>  
> -@item -net nic[,vlan=@var{n}][,macaddr=@var{addr}][,model=@var{type}]
> -Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
> +@item -net nic[,vnet=@var{n}][,macaddr=@var{addr}][,model=@var{type}]
> +Create a new Network Interface Card and connect it to VNET @var{n} (@var{n}
>  = 0 is the default). The NIC is an ne2k_pci by default on the PC
>  target. Optionally, the MAC address can be changed. If no
>  @option{-net} option is specified, a single NIC is created.
> @@ -617,13 +617,13 @@
>  Not all devices are supported on all targets.  Use -net nic,model=?
>  for a list of available devices for your target.
>  
> -@item -net user[,vlan=@var{n}][,hostname=@var{name}]
> +@item -net user[,vnet=@var{n}][,hostname=@var{name}]
>  Use the user mode network stack which requires no administrator
>  privilege to run.  @option{hostname=name} can be used to specify the client
>  hostname reported by the builtin DHCP server.
>  
> -@item -net tap[,vlan=@var{n}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}]
> -Connect the host TAP network interface @var{name} to VLAN @var{n}, use
> +@item -net tap[,vnet=@var{n}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}]
> +Connect the host TAP network interface @var{name} to VNET @var{n}, 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 
>  automatically provides one. @option{fd}=@var{h} can be used to specify
> @@ -638,14 +638,14 @@
>  
>  More complicated example (two NICs, each one connected to a TAP device)
>  @example
> -qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
> -               -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
> +qemu linux.img -net nic,vnet=0 -net tap,vnet=0,ifname=tap0 \
> +               -net nic,vnet=1 -net tap,vnet=1,ifname=tap1
>  @end example
>  
>  
> -@item -net socket[,vlan=@var{n}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
> +@item -net socket[,vnet=@var{n}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
>  
> -Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
> +Connect the VNET @var{n} to a remote VNET in 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
> @@ -657,15 +657,15 @@
>  # launch a first QEMU instance
>  qemu 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
> +# connect the VNET 0 of this instance to the VNET 0
>  # of the first instance
>  qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
>                 -net socket,connect=127.0.0.1:1234
>  @end example
>  
> -@item -net socket[,vlan=@var{n}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]
> +@item -net socket[,vnet=@var{n}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]
>  
> -Create a VLAN @var{n} shared with another QEMU virtual
> +Create a VNET @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}.
>  NOTES:
> @@ -703,8 +703,8 @@
>  /path/to/linux ubd0=/path/to/root_fs eth0=mcast
>  @end example
>  
> -@item -net vde[,vlan=@var{n}][,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
> -Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
> +@item -net vde[,vnet=@var{n}][,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
> +Connect VNET @var{n} 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 available only if QEMU has been compiled
> @@ -816,14 +816,14 @@
>  @code{hci0}) on the computer running QEMU.  Only available on @code{bluez}
>  capable systems like Linux.
>  
> -@item -bt hci[,vlan=@var{n}]
> +@item -bt hci[,vnet=@var{n}]
>  Add a virtual, standard HCI that will participate in the Bluetooth
>  scatternet @var{n} (default @code{0}).  Similarly to @option{-net}
> -VLANs, devices inside a bluetooth network @var{n} can only communicate
> +VNETs, devices inside a bluetooth network @var{n} can only communicate
>  with other devices in the same network (scatternet).
>  @end table
>  
> -@item -bt vhci[,vlan=@var{n}]
> +@item -bt vhci[,vnet=@var{n}]
>  (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
>  to the host bluetooth stack instead of to the emulated target.  This
>  allows the host and target machines to participate in a common scatternet
> @@ -831,10 +831,10 @@
>  be used as following:
>  
>  @example
> -qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
> +qemu [...OPTIONS...] -bt hci,vnet=5 -bt vhci,vnet=5
>  @end example
>  
> -@item -bt device:@var{dev}[,vlan=@var{n}]
> +@item -bt device:@var{dev}[,vnet=@var{n}]
>  Emulate a bluetooth device @var{dev} and place it in network @var{n}
>  (default @code{0}).  QEMU can only emulate one type of bluetooth devices
>  currently:
> @@ -1194,7 +1194,7 @@
>  
>  @table @option
>  @item info network
> -show the various VLANs and the associated devices
> +show the various VNETs and the associated devices
>  @item info block
>  show the block devices
>  @item info registers
> @@ -1658,16 +1658,16 @@
>  @section Network emulation
>  
>  QEMU can simulate several network cards (PCI or ISA cards on the PC
> -target) and can connect them to an arbitrary number of Virtual Local
> -Area Networks (VLANs). Host TAP devices can be connected to any QEMU
> -VLAN. VLAN can be connected between separate instances of QEMU to
> +target) and can connect them to an arbitrary number of Virtual 
> +Networks (VNETs). Host TAP devices can be connected to any QEMU
> +VNET. VNET can be connected between separate instances of QEMU to
>  simulate large networks. For simpler usage, a non privileged user mode
>  network stack can replace the TAP device to have a basic network
>  connection.
>  
> -@subsection VLANs
> +@subsection VNETs
>  
> -QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
> +QEMU simulates several VNETs. A VNET can be symbolised as a virtual
>  connection between several network devices. These devices can be for
>  example QEMU virtual Ethernet cards or virtual Host ethernet devices
>  (TAP devices).
> @@ -1706,7 +1706,7 @@
>  
>  @example
>  
> -         QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
> +         QEMU VNET      <------>  Firewall/DHCP server <-----> Internet
>                             |          (10.0.2.2)
>                             |
>                             ---->  DNS server (10.0.2.3)
> @@ -1734,9 +1734,9 @@
>  redirected from the host to the guest. It allows for example to
>  redirect X11, telnet or SSH connections.
>  
> -@subsection Connecting VLANs between QEMU instances
> +@subsection Connecting VNETs between QEMU instances
>  
> -Using the @option{-net socket} option, it is possible to make VLANs
> +Using the @option{-net socket} option, it is possible to make VNETs
>  that span several QEMU instances. See @ref{sec_invocation} to have a
>  basic example.
>  
> @@ -1828,17 +1828,17 @@
>  specifies NIC options as with @code{-net nic,}@var{options} (see description).
>  For instance, user-mode networking can be used with
>  @example
> -qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
> +qemu [...OPTIONS...] -net user,vnet=0 -usbdevice net:vnet=0
>  @end example
>  Currently this cannot be used in machines that support PCI NICs.
>  @item bt[:@var{hci-type}]
>  Bluetooth dongle whose type is specified in the same format as with
>  the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
> -no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
> +no type is given, the HCI logic corresponds to @code{-bt hci,vnet=0}.
>  This USB device implements the USB Transport Layer of HCI.  Example
>  usage:
>  @example
> -qemu [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
> +qemu [...OPTIONS...] -usbdevice bt:hci,vnet=3 -bt device:keyboard,vnet=3
>  @end example
>  @end table
>  


This documentation change needs to explicitly tell people that vnet=
is the new name of vlan=.  WIthout this you're going to confuse people
reading all the QEMU argv example on the net who are searching for
what vlan= means and finding no trace of it in the docs.

Daniel
-- 
|: Red Hat, Engineering, London   -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org  -o-  http://virt-manager.org  -o-  http://ovirt.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-  F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|