[Qemu-devel] [5806] qemu-doc.texi: document downscript network option

[Qemu-devel] [5806] qemu-doc.texi: document downscript network option

[Aurelien Jarno]

Revision: 5806
          http://svn.sv.gnu.org/viewvc/?view=rev&root=qemu&revision=5806
Author:   aurel32
Date:     2008-11-28 10:11:17 +0000 (Fri, 28 Nov 2008)

Log Message:
-----------
qemu-doc.texi: document downscript network option

>From Guido G?\195?\188nther, through the Debian BTS.

Modified Paths:
--------------
    trunk/qemu-doc.texi

Modified: trunk/qemu-doc.texi
===================================================================
--- trunk/qemu-doc.texi	2008-11-27 19:30:56 UTC (rev 5805)
+++ trunk/qemu-doc.texi	2008-11-28 10:11:17 UTC (rev 5806)
@@ -616,13 +616,15 @@
 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}]
+@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} and
 use the network script @var{file} to configure it. The default
 network script is @file{/etc/qemu-ifup}. Use @option{script=no} to
-disable script execution. If @var{name} is not
-provided, the OS automatically provides one. @option{fd}=@var{h} can be
-used to specify the handle of an already opened host TAP interface. Example:
+disable script execution. If @var{name} is not provided, the OS automatically
+provides one. Use network script @var{dfile} to deconfigure the interface. Use
+@option{downscript=no} to disable script execution. @option{fd}=@var{h} can be
+used to specify the handle of an already opened host TAP interface.
+Example:
 
 @example
 qemu linux.img -net nic -net tap

Re: [Qemu-devel] [5806] qemu-doc.texi: document downscript network option

[Jamie Lokier]

Aurelien Jarno wrote a patch, resulting in:
> @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}
> and use the network script @var{file} to configure it. The default
> network script is @file{/etc/qemu-ifup}. Use @option{script=no} to
> disable script execution. If @var{name} is not provided, the OS
> automatically provides one. Use network script @var{dfile} to
> deconfigure the interface. Use @option{downscript=no} to disable
> script execution. @option{fd}=@var{h} can be used to specify the
> handle of an already opened host TAP interface.

Two things don't make sense:

   1. Do you have to write "downscript=no" to disable
      downscript execution?  If you don't need it, that part of the
      documentation is unnecessary.  If you do need it, then it's not
      backward-compatible with earlier QEMU versions.

   2. If you do need "downscript=no" to disable it, what's
      the default downscript name if you don't have "downscript=no"?

Also, it would be better for the text to describe the options in the
same order as the synopsis in the first line, especially describing
the two script options without anything else between.

-- Jamie

Re: [Qemu-devel] [5806] qemu-doc.texi: document downscript network option

[Aurelien Jarno]

Jamie Lokier a écrit :
> Aurelien Jarno wrote a patch, resulting in:
>> @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}
>> and use the network script @var{file} to configure it. The default
>> network script is @file{/etc/qemu-ifup}. Use @option{script=no} to
>> disable script execution. If @var{name} is not provided, the OS
>> automatically provides one. Use network script @var{dfile} to
>> deconfigure the interface. Use @option{downscript=no} to disable
>> script execution. @option{fd}=@var{h} can be used to specify the
>> handle of an already opened host TAP interface.
> 
> Two things don't make sense:
> 
>    1. Do you have to write "downscript=no" to disable
>       downscript execution?  If you don't need it, that part of the
>       documentation is unnecessary.  If you do need it, then it's not
>       backward-compatible with earlier QEMU versions.
>
> 
>    2. If you do need "downscript=no" to disable it, what's
>       the default downscript name if you don't have "downscript=no"?
>

By default it uses /etc/qemu-ifdown. You have to set downscript=no to
disabled that.

Note that the code hasn't changed, so there is no worry about backward
compatiblity. This behaviour is already present in qemu 0.9.1 (and
probably in previous versions). It is only undocumented.

> Also, it would be better for the text to describe the options in the
> same order as the synopsis in the first line, especially describing
> the two script options without anything else between.
> 

All that should be fixed in revision r5807.

-- 
  .''`.  Aurelien Jarno	            | GPG: 1024D/F1BCDB73
 : :' :  Debian developer           | Electrical Engineer
 `. `'   aurel32@debian.org         | aurelien@aurel32.net
   `-    people.debian.org/~aurel32 | www.aurel32.net