Patchwork Add -netdev to man page

login
register
mail settings
Submitter Miroslav Rezanina
Date March 1, 2012, 1:57 p.m.
Message ID <524d8e6b-3edf-4a78-8449-932d11bb2201@zmail17.collab.prod.int.phx2.redhat.com>
Download mbox | patch
Permalink /patch/144015/
State New
Headers show

Comments

Miroslav Rezanina - March 1, 2012, 1:57 p.m.
There's missing -netdev description in the man page for qemu. As this is
recommended way to create network backend, lack of documentation can discourage
its usage.

-net option is preserved but marked as obsolete way.

Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>

Patch:
-----
Markus Armbruster - March 1, 2012, 3:50 p.m.
Miroslav Rezanina <mrezanin@redhat.com> writes:

> There's missing -netdev description in the man page for qemu. As this is
> recommended way to create network backend, lack of documentation can discourage
> its usage.

Very much appreciated!

> -net option is preserved but marked as obsolete way.
>
> Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>
>
> Patch:
> -----
> diff --git a/qemu-options.hx b/qemu-options.hx
> index b129996..a1d61b6 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1292,6 +1292,268 @@ DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
>  #endif
>      "socket],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL)
>  STEXI
> +@item -netdev user|tap|vde|socket,id=@var{str}[,option][,option][,...]
> +
> +Create a new network backend to the guest. The backend's @option{id} can be used with

Suggest to drop "to the guest".

> +the @option{-device} option to connect a backend with a device, 
> +e.g.
> +
> +@example
> +-netdev user,id=mynet -device e1000,netdev=mynet
> +@end example
> +
> +You can use following types of backend:
> +
> +@table @option
> +
> +@item -netdev user
> +
> +User networking is default network backend. This backend does not require root 
> +priviledges, does not allow ICMP trafic and host is not directly accessible 
> +from the host or the external network.

privileges

traffic

Suggest you use a spell checker :)

Comma after "traffic", please.

Err, "host is not directly accessible from the host"...  Do you mean
"guest is not"?

> +Valid options are:
> +
> +@table @option
> +
> +@item restrict=y|yes|n|no

For -net, this is documented as restrict=on|off.  All these values are
actually recognized.  I find that somewhat baroque, and don't
particularly care which ones you document :)

> +If this options is enabled, the guest will be isolated, i.e. it will not be

option

> +able to contact the host and no guest IP packets will be routed over the host
> +to the outside. This option does not affect explicitly set forwarding rules.
> +
> +@item net=@var{addr}[/@var{mask}]
> +Set the IP network address the guest will see. Optionally specify the netmask,
> +either in the form a.b.c.d or as number of valid top-most bits. Default is
> +10.0.2.0/8.

Documentation of -net has /24 here.  One of them might be wrong (I
didn't check).

> +
> +@item host=@var{addr}
> +Specify the guest-visible address of the host. Default is the 2nd IP in the
> +guest network, i.e. x.x.x.2.
> +
> +@item hostname=@var{name}
> +Specifies the client hostname reported by the builtin DHCP server.
> +
> +@item dhcpstart=@var{addr}
> +Specify the first of the 16 IPs the built-in DHCP server can assign. Default
> +is the 16th to 31st IP in the guest network, i.e. x.x.x.16 to x.x.x.31.

Documentation of -net has 15th here.  One of them might be wrong (I
didn't check).

> +@item dns=@var{addr}
> +Specify the guest-visible address of the virtual nameserver. The address must
> +be different from the host address. Default is the 3rd IP in the guest network,
> +i.e. x.x.x.3.
> +
> +@item tftp=@var{dir}
> +When using the user mode network stack, activate a built-in TFTP
> +server. The files in @var{dir} will be exposed as the root of a TFTP server.
> +The TFTP client on the guest must be configured in binary mode (use the command
> +@code{bin} of the Unix TFTP client).
> +
> +@item bootfile=@var{file}
> +When using the user mode network stack, broadcast @var{file} as the BOOTP
> +filename. In conjunction with @option{tftp}, this can be used to network boot
> +a guest from a local directory.
> +
> +Example (using pxelinux):
> +@example
> +qemu -hda linux.img -boot n -netdev user,id=netid,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
> +@end example
> +
> +@item smb=@var{dir}[,smbserver=@var{addr}]
> +When using the user mode network stack, activate a built-in SMB
> +server so that Windows OSes can access to the host files in @file{@var{dir}}
> +transparently. The IP address of the SMB server can be set to @var{addr}. By
> +default the 4th IP in the guest network is used, i.e. x.x.x.4.
> +
> +In the guest Windows OS, the line:
> +@example
> +10.0.2.4 smbserver
> +@end example
> +must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
> +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 in
> +@file{/usr/sbin/smbd}. QEMU was tested successfully with smbd versions from
> +Red Hat 9, Fedora Core 3 and OpenSUSE 11.x.
> +
> +@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
> +the guest IP address @var{guestaddr} on guest port @var{guestport}. If
> +@var{guestaddr} is not specified, its value is x.x.x.15 (default first address
> +given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
> +be bound to a specific host interface. If no connection type is set, TCP is
> +used. This option can be given multiple times.
> +
> +For example, to redirect host X11 connection from screen 1 to guest
> +screen 0, use the following:
> +
> +@example
> +# on the host
> +qemu -netdev user,id=netid,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
> +# this host xterm should open in the guest X11 server
> +xterm -display :1
> +@end example
> +
> +To redirect telnet connections from host port 5555 to telnet port on
> +the guest, use the following:
> +
> +@example
> +# on the host
> +qemu -netdev user,id=netid,hostfwd=tcp:5555::23 [...]
> +telnet localhost 5555
> +@end example
> +
> +Then when you use on the host @code{telnet localhost 5555}, you
> +connect to the guest telnet server.
> +
> +@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
> +Forward guest TCP connections to the IP address @var{server} on port @var{port}
> +to the character device @var{dev}. This option can be given multiple times.
> +
> +@end table
> +
> +@item -netdev tap
> +
> +The tap networking backend makes use of a tap networking device in the host. 
> +It offers very good performance and can be configured to create virtually 
> +any type of network topology. It requires configuration of that network 
> +topology in the host and invoking QEMU as root unless the tap device has been
> +preconfigured to be owned by the user invoking qemu, or the @option{f}d option is used

@option{fd}

Since you're discussing non-root tap setup, perhaps point to the helper
option as well.

> +
> +Valid options are:
> +
> +@table @option
> +
> +@item ifname=@var{name}
> +Name of host tap device to be used by qemu. 
> +
> +@item fd=@var{descriptor}
> +File descriptor of an already opened tap.
> +
> +@item script=@var{scriptpath}
> +Network script used to configure device.
> +
> +@item downscript=@var{scriptpath}
> +Network script used to deconfigure device.
> +
> +@item sndbuf=@var{size}
> +Limit for send buffer.
> +
> +@item vnet_hdr=on|off]
> +Enable the IFF_VNET_HDR flag on the tap interface.
> +
> +@item vhost=[on|off]
> +Enable vhost-net network accelerator.
> +
> +@item vhostfd=@var{descriptor}
> +File descriptor of an already opened vhost-net device.
> +
> +@item vhostforce=[on|off]
> +Force 'vhost=on' for non-MSIX virtio guests.
> +
> +@item helper=@var{helper}
> +If running QEMU as an unprivileged user, use the network helper
> +@var{helper} to configure the TAP interface. The default network
> +helper executable is @file{/usr/local/libexec/qemu-bridge-helper}.

Should this be #ifdef CONFIG_NET_BRIDGE?

> +
> +@end table
> +ETEXI
> +#ifdef CONFIG_VDE
> +STEXI
> +@item -netdev vde
> +
> +Virtual Distributed Ethernet infrastructure is used. Unless you specifically
> +know that you want to use VDE, it is probably not the best backend to use. This option
> +is only available if QEMU has been compiled with vde support enabled.
> +
> +Valid options are:
> +
> +@table @option
> +
> +@item sock=@var{socketpath}
> +
> +Path to the socket used for backend.
> +
> +@item port=@var{n}
> +
> +Port number.
> +
> +@item group=@var{groupname}
> +
> +Owner group for the used socket.
> +
> +@item mode=@var{octalmode}
> +
> +File permissions of used socket.
> +
> +@end table
> +
> +ETEXI
> +#endif
> +STEXI
> +
> +@item -netdev socket
> +
> +The socket networking backend allow you to create a network of guests that can
> +see each other. It's primarily useful in extending the network created by slirp
> +to multiple virtual machines. 
> +
> +One of following options has to be specified:
> +
> +@table @option
> +
> +@item fd @var{descriptor}
> +Qemu uses an already opened socket with file descriptor @var{descriptor}
> +
> +@item listen [@var{hostname}]:@var{port}
> +Specify port, and optionaly hostname, qemu will listen on.
> +
> +@item connect [@var{hostname}]:@var{port}
> +Qemu connects to specified port and, optionaly, hostname.
> +
> +@item mcast @var{addr}
> +Qemu uses UDP multicast address @var{addr}.
> +
> +@item udp @var{addr}:@var{port}
> +Qemu uses UDP unicast address and port.
> +
> +@end table
> +
> +Option @option{localaddr}=@var{addr}:@var{port} can be used for @option{mcast}
> +and has to be used for @option{udp} option. It specifiy source address and port 
> +for udp packets.
> +
> +ETEXI
> +#ifdef CONFIG_NET_BRIDGE
> +STEXI
> +
> +@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
> +Connect a host TAP network interface to a host bridge device. This option is
> +only available if QEMU has been compiled with net brdige support enabled.

bridge

> +
> +Valid options are:
> +
> +@table @option
> +
> +@item br=@var{bridge}
> +Specify bridge TAP interface should be attached. Default value is @file{br0}.
> +
> +@item helper=@var{helper}
> +Network helper used to configure TAP inteface. Default helper is 
> +@file{/usr/local/libexec/qemu-bridge-helper}.
> +
> +@end table
> +ETEXI
> +#endif
> +STEXI
> +@end table
> +@end table
> +
> +Following options for backend creation are obsolete but still working:
> +
> +@table @option
> +
>  @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
>  @findex -net
>  Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
Miroslav Rezanina - March 1, 2012, 5:58 p.m.
Hi Markus,
thanks for comments see inline:

----- Original Message -----
> From: "Markus Armbruster" <armbru@redhat.com>
> To: "Miroslav Rezanina" <mrezanin@redhat.com>
> Cc: qemu-devel@nongnu.org
> Sent: Thursday, March 1, 2012 4:50:35 PM
> Subject: Re: [Qemu-devel] [PATCH] Add -netdev to man page
> 
> Miroslav Rezanina <mrezanin@redhat.com> writes:
> 
> > There's missing -netdev description in the man page for qemu. As
> > this is
> > recommended way to create network backend, lack of documentation
> > can discourage
> > its usage.
> 
> Very much appreciated!
> 
> > -net option is preserved but marked as obsolete way.
> >
> > Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>
> >
> > Patch:
> > -----
> > diff --git a/qemu-options.hx b/qemu-options.hx
> > index b129996..a1d61b6 100644
> > --- a/qemu-options.hx
> > +++ b/qemu-options.hx
> > @@ -1292,6 +1292,268 @@ DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
> >  #endif
> >      "socket],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL)
> >  STEXI
> > +@item -netdev
> > user|tap|vde|socket,id=@var{str}[,option][,option][,...]
> > +
> > +Create a new network backend to the guest. The backend's
> > @option{id} can be used with
> 
> Suggest to drop "to the guest".
> 
> > +the @option{-device} option to connect a backend with a device,
> > +e.g.
> > +
> > +@example
> > +-netdev user,id=mynet -device e1000,netdev=mynet
> > +@end example
> > +
> > +You can use following types of backend:
> > +
> > +@table @option
> > +
> > +@item -netdev user
> > +
> > +User networking is default network backend. This backend does not
> > require root
> > +priviledges, does not allow ICMP trafic and host is not directly
> > accessible
> > +from the host or the external network.
> 
> privileges
> 
> traffic
> 
> Suggest you use a spell checker :)
> 
> Comma after "traffic", please.
> 
> Err, "host is not directly accessible from the host"...  Do you mean
> "guest is not"?

Yeah, I have to find one...As I rewrite code too often, I'm blind to this.
> 
> > +Valid options are:
> > +
> > +@table @option
> > +
> > +@item restrict=y|yes|n|no
> 
> For -net, this is documented as restrict=on|off.  All these values
> are
> actually recognized.  I find that somewhat baroque, and don't
> particularly care which ones you document :)
> 
> > +If this options is enabled, the guest will be isolated, i.e. it
> > will not be
> 
> option

What documentation do you mean?? It's look like there's more differences
to check.

> 
> > +able to contact the host and no guest IP packets will be routed
> > over the host
> > +to the outside. This option does not affect explicitly set
> > forwarding rules.
> > +
> > +@item net=@var{addr}[/@var{mask}]
> > +Set the IP network address the guest will see. Optionally specify
> > the netmask,
> > +either in the form a.b.c.d or as number of valid top-most bits.
> > Default is
> > +10.0.2.0/8.
> 
> Documentation of -net has /24 here.  One of them might be wrong (I
> didn't check).
> 
> > +
> > +@item host=@var{addr}
> > +Specify the guest-visible address of the host. Default is the 2nd
> > IP in the
> > +guest network, i.e. x.x.x.2.
> > +
> > +@item hostname=@var{name}
> > +Specifies the client hostname reported by the builtin DHCP server.
> > +
> > +@item dhcpstart=@var{addr}
> > +Specify the first of the 16 IPs the built-in DHCP server can
> > assign. Default
> > +is the 16th to 31st IP in the guest network, i.e. x.x.x.16 to
> > x.x.x.31.
> 
> Documentation of -net has 15th here.  One of them might be wrong (I
> didn't check).
> 
> > +@item dns=@var{addr}
> > +Specify the guest-visible address of the virtual nameserver. The
> > address must
> > +be different from the host address. Default is the 3rd IP in the
> > guest network,
> > +i.e. x.x.x.3.
> > +
> > +@item tftp=@var{dir}
> > +When using the user mode network stack, activate a built-in TFTP
> > +server. The files in @var{dir} will be exposed as the root of a
> > TFTP server.
> > +The TFTP client on the guest must be configured in binary mode
> > (use the command
> > +@code{bin} of the Unix TFTP client).
> > +
> > +@item bootfile=@var{file}
> > +When using the user mode network stack, broadcast @var{file} as
> > the BOOTP
> > +filename. In conjunction with @option{tftp}, this can be used to
> > network boot
> > +a guest from a local directory.
> > +
> > +Example (using pxelinux):
> > +@example
> > +qemu -hda linux.img -boot n -netdev
> > user,id=netid,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
> > +@end example
> > +
> > +@item smb=@var{dir}[,smbserver=@var{addr}]
> > +When using the user mode network stack, activate a built-in SMB
> > +server so that Windows OSes can access to the host files in
> > @file{@var{dir}}
> > +transparently. The IP address of the SMB server can be set to
> > @var{addr}. By
> > +default the 4th IP in the guest network is used, i.e. x.x.x.4.
> > +
> > +In the guest Windows OS, the line:
> > +@example
> > +10.0.2.4 smbserver
> > +@end example
> > +must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows
> > 9x/Me)
> > +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 in
> > +@file{/usr/sbin/smbd}. QEMU was tested successfully with smbd
> > versions from
> > +Red Hat 9, Fedora Core 3 and OpenSUSE 11.x.
> > +
> > +@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
> > +the guest IP address @var{guestaddr} on guest port
> > @var{guestport}. If
> > +@var{guestaddr} is not specified, its value is x.x.x.15 (default
> > first address
> > +given by the built-in DHCP server). By specifying @var{hostaddr},
> > the rule can
> > +be bound to a specific host interface. If no connection type is
> > set, TCP is
> > +used. This option can be given multiple times.
> > +
> > +For example, to redirect host X11 connection from screen 1 to
> > guest
> > +screen 0, use the following:
> > +
> > +@example
> > +# on the host
> > +qemu -netdev user,id=netid,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
> > +# this host xterm should open in the guest X11 server
> > +xterm -display :1
> > +@end example
> > +
> > +To redirect telnet connections from host port 5555 to telnet port
> > on
> > +the guest, use the following:
> > +
> > +@example
> > +# on the host
> > +qemu -netdev user,id=netid,hostfwd=tcp:5555::23 [...]
> > +telnet localhost 5555
> > +@end example
> > +
> > +Then when you use on the host @code{telnet localhost 5555}, you
> > +connect to the guest telnet server.
> > +
> > +@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
> > +Forward guest TCP connections to the IP address @var{server} on
> > port @var{port}
> > +to the character device @var{dev}. This option can be given
> > multiple times.
> > +
> > +@end table
> > +
> > +@item -netdev tap
> > +
> > +The tap networking backend makes use of a tap networking device in
> > the host.
> > +It offers very good performance and can be configured to create
> > virtually
> > +any type of network topology. It requires configuration of that
> > network
> > +topology in the host and invoking QEMU as root unless the tap
> > device has been
> > +preconfigured to be owned by the user invoking qemu, or the
> > @option{f}d option is used
> 
> @option{fd}
> 
> Since you're discussing non-root tap setup, perhaps point to the
> helper
> option as well.
> 
Good point.
> > +
> > +Valid options are:
> > +
> > +@table @option
> > +
> > +@item ifname=@var{name}
> > +Name of host tap device to be used by qemu.
> > +
> > +@item fd=@var{descriptor}
> > +File descriptor of an already opened tap.
> > +
> > +@item script=@var{scriptpath}
> > +Network script used to configure device.
> > +
> > +@item downscript=@var{scriptpath}
> > +Network script used to deconfigure device.
> > +
> > +@item sndbuf=@var{size}
> > +Limit for send buffer.
> > +
> > +@item vnet_hdr=on|off]
> > +Enable the IFF_VNET_HDR flag on the tap interface.
> > +
> > +@item vhost=[on|off]
> > +Enable vhost-net network accelerator.
> > +
> > +@item vhostfd=@var{descriptor}
> > +File descriptor of an already opened vhost-net device.
> > +
> > +@item vhostforce=[on|off]
> > +Force 'vhost=on' for non-MSIX virtio guests.
> > +
> > +@item helper=@var{helper}
> > +If running QEMU as an unprivileged user, use the network helper
> > +@var{helper} to configure the TAP interface. The default network
> > +helper executable is @file{/usr/local/libexec/qemu-bridge-helper}.
> 
> Should this be #ifdef CONFIG_NET_BRIDGE?
> 
Yeah, helper is in #ifdef. However, preprocessing does not work with man
page generation so it is used here as reminder only and do not have any
influence on generated result.
> > +
> > +@end table
> > +ETEXI
> > +#ifdef CONFIG_VDE
> > +STEXI
> > +@item -netdev vde
> > +
> > +Virtual Distributed Ethernet infrastructure is used. Unless you
> > specifically
> > +know that you want to use VDE, it is probably not the best backend
> > to use. This option
> > +is only available if QEMU has been compiled with vde support
> > enabled.
> > +
> > +Valid options are:
> > +
> > +@table @option
> > +
> > +@item sock=@var{socketpath}
> > +
> > +Path to the socket used for backend.
> > +
> > +@item port=@var{n}
> > +
> > +Port number.
> > +
> > +@item group=@var{groupname}
> > +
> > +Owner group for the used socket.
> > +
> > +@item mode=@var{octalmode}
> > +
> > +File permissions of used socket.
> > +
> > +@end table
> > +
> > +ETEXI
> > +#endif
> > +STEXI
> > +
> > +@item -netdev socket
> > +
> > +The socket networking backend allow you to create a network of
> > guests that can
> > +see each other. It's primarily useful in extending the network
> > created by slirp
> > +to multiple virtual machines.
> > +
> > +One of following options has to be specified:
> > +
> > +@table @option
> > +
> > +@item fd @var{descriptor}
> > +Qemu uses an already opened socket with file descriptor
> > @var{descriptor}
> > +
> > +@item listen [@var{hostname}]:@var{port}
> > +Specify port, and optionaly hostname, qemu will listen on.
> > +
> > +@item connect [@var{hostname}]:@var{port}
> > +Qemu connects to specified port and, optionaly, hostname.
> > +
> > +@item mcast @var{addr}
> > +Qemu uses UDP multicast address @var{addr}.
> > +
> > +@item udp @var{addr}:@var{port}
> > +Qemu uses UDP unicast address and port.
> > +
> > +@end table
> > +
> > +Option @option{localaddr}=@var{addr}:@var{port} can be used for
> > @option{mcast}
> > +and has to be used for @option{udp} option. It specifiy source
> > address and port
> > +for udp packets.
> > +
> > +ETEXI
> > +#ifdef CONFIG_NET_BRIDGE
> > +STEXI
> > +
> > +@item -netdev
> > bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
> > +Connect a host TAP network interface to a host bridge device. This
> > option is
> > +only available if QEMU has been compiled with net brdige support
> > enabled.
> 
> bridge
> 
> > +
> > +Valid options are:
> > +
> > +@table @option
> > +
> > +@item br=@var{bridge}
> > +Specify bridge TAP interface should be attached. Default value is
> > @file{br0}.
> > +
> > +@item helper=@var{helper}
> > +Network helper used to configure TAP inteface. Default helper is
> > +@file{/usr/local/libexec/qemu-bridge-helper}.
> > +
> > +@end table
> > +ETEXI
> > +#endif
> > +STEXI
> > +@end table
> > +@end table
> > +
> > +Following options for backend creation are obsolete but still
> > working:
> > +
> > +@table @option
> > +
> >  @item -net
> >  nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}]
> >  [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
> >  @findex -net
> >  Create a new Network Interface Card and connect it to VLAN @var{n}
> >  (@var{n}
> 

Regards,
Mirek
Miroslav Rezanina - March 3, 2012, 7:32 p.m.
----- Original Message -----
> From: "Markus Armbruster" <armbru@redhat.com>
> To: "Miroslav Rezanina" <mrezanin@redhat.com>
> Cc: qemu-devel@nongnu.org
> Sent: Thursday, March 1, 2012 4:50:35 PM
> Subject: Re: [Qemu-devel] [PATCH] Add -netdev to man page
> 
> Miroslav Rezanina <mrezanin@redhat.com> writes:
> 
> > There's missing -netdev description in the man page for qemu. As
> > this is
> > recommended way to create network backend, lack of documentation
> > can discourage
> > its usage.
> 
> Very much appreciated!
> 
> > -net option is preserved but marked as obsolete way.
> >
> > Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>
> >
> > Patch:
> > -----
> > diff --git a/qemu-options.hx b/qemu-options.hx
> > index b129996..a1d61b6 100644
> > --- a/qemu-options.hx
> > +++ b/qemu-options.hx
> > @@ -1292,6 +1292,268 @@ DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
> >  #endif
> >      "socket],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL)
> >  STEXI
> > +@item -netdev
> > user|tap|vde|socket,id=@var{str}[,option][,option][,...]
> > +
> > +Create a new network backend to the guest. The backend's
> > @option{id} can be used with
> 
> Suggest to drop "to the guest".
> 
ok.

> > +the @option{-device} option to connect a backend with a device,
> > +e.g.
> > +
> > +@example
> > +-netdev user,id=mynet -device e1000,netdev=mynet
> > +@end example
> > +
> > +You can use following types of backend:
> > +
> > +@table @option
> > +
> > +@item -netdev user
> > +
> > +User networking is default network backend. This backend does not
> > require root
> > +priviledges, does not allow ICMP trafic and host is not directly
> > accessible
> > +from the host or the external network.
> 
> privileges
> 
> traffic
> 
> Suggest you use a spell checker :)
> 
> Comma after "traffic", please.
> 
> Err, "host is not directly accessible from the host"...  Do you mean
> "guest is not"?
> 
> > +Valid options are:
> > +
> > +@table @option
> > +
> > +@item restrict=y|yes|n|no
> 
> For -net, this is documented as restrict=on|off.  All these values
> are
> actually recognized.  I find that somewhat baroque, and don't
> particularly care which ones you document :)
>

I will go on|off way even if yes|no is possible. No need to use special
handling.
 
> > +If this options is enabled, the guest will be isolated, i.e. it
> > will not be
> 
> option
> 
> > +able to contact the host and no guest IP packets will be routed
> > over the host
> > +to the outside. This option does not affect explicitly set
> > forwarding rules.
> > +
> > +@item net=@var{addr}[/@var{mask}]
> > +Set the IP network address the guest will see. Optionally specify
> > the netmask,
> > +either in the form a.b.c.d or as number of valid top-most bits.
> > Default is
> > +10.0.2.0/8.
> 
> Documentation of -net has /24 here.  One of them might be wrong (I
> didn't check).
> 

You're right. I worked on both RHEL and upstream man page in paralel and
there's different text in both version. Correct value is /24.

> > +
> > +@item host=@var{addr}
> > +Specify the guest-visible address of the host. Default is the 2nd
> > IP in the
> > +guest network, i.e. x.x.x.2.
> > +
> > +@item hostname=@var{name}
> > +Specifies the client hostname reported by the builtin DHCP server.
> > +
> > +@item dhcpstart=@var{addr}
> > +Specify the first of the 16 IPs the built-in DHCP server can
> > assign. Default
> > +is the 16th to 31st IP in the guest network, i.e. x.x.x.16 to
> > x.x.x.31.
> 
> Documentation of -net has 15th here.  One of them might be wrong (I
> didn't check).

Yes, 15 is correct start but I'm not sure with end value -> is 16 IP used
so last address is x.x.x.30 or is x.x.x.31 really last address?

> 
> > +@item dns=@var{addr}
> > +Specify the guest-visible address of the virtual nameserver. The
> > address must
> > +be different from the host address. Default is the 3rd IP in the
> > guest network,
> > +i.e. x.x.x.3.
> > +
> > +@item tftp=@var{dir}
> > +When using the user mode network stack, activate a built-in TFTP
> > +server. The files in @var{dir} will be exposed as the root of a
> > TFTP server.
> > +The TFTP client on the guest must be configured in binary mode
> > (use the command
> > +@code{bin} of the Unix TFTP client).
> > +
> > +@item bootfile=@var{file}
> > +When using the user mode network stack, broadcast @var{file} as
> > the BOOTP
> > +filename. In conjunction with @option{tftp}, this can be used to
> > network boot
> > +a guest from a local directory.
> > +
> > +Example (using pxelinux):
> > +@example
> > +qemu -hda linux.img -boot n -netdev
> > user,id=netid,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
> > +@end example
> > +
> > +@item smb=@var{dir}[,smbserver=@var{addr}]
> > +When using the user mode network stack, activate a built-in SMB
> > +server so that Windows OSes can access to the host files in
> > @file{@var{dir}}
> > +transparently. The IP address of the SMB server can be set to
> > @var{addr}. By
> > +default the 4th IP in the guest network is used, i.e. x.x.x.4.
> > +
> > +In the guest Windows OS, the line:
> > +@example
> > +10.0.2.4 smbserver
> > +@end example
> > +must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows
> > 9x/Me)
> > +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 in
> > +@file{/usr/sbin/smbd}. QEMU was tested successfully with smbd
> > versions from
> > +Red Hat 9, Fedora Core 3 and OpenSUSE 11.x.
> > +
> > +@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
> > +the guest IP address @var{guestaddr} on guest port
> > @var{guestport}. If
> > +@var{guestaddr} is not specified, its value is x.x.x.15 (default
> > first address
> > +given by the built-in DHCP server). By specifying @var{hostaddr},
> > the rule can
> > +be bound to a specific host interface. If no connection type is
> > set, TCP is
> > +used. This option can be given multiple times.
> > +
> > +For example, to redirect host X11 connection from screen 1 to
> > guest
> > +screen 0, use the following:
> > +
> > +@example
> > +# on the host
> > +qemu -netdev user,id=netid,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
> > +# this host xterm should open in the guest X11 server
> > +xterm -display :1
> > +@end example
> > +
> > +To redirect telnet connections from host port 5555 to telnet port
> > on
> > +the guest, use the following:
> > +
> > +@example
> > +# on the host
> > +qemu -netdev user,id=netid,hostfwd=tcp:5555::23 [...]
> > +telnet localhost 5555
> > +@end example
> > +
> > +Then when you use on the host @code{telnet localhost 5555}, you
> > +connect to the guest telnet server.
> > +
> > +@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
> > +Forward guest TCP connections to the IP address @var{server} on
> > port @var{port}
> > +to the character device @var{dev}. This option can be given
> > multiple times.
> > +
> > +@end table
> > +
> > +@item -netdev tap
> > +
> > +The tap networking backend makes use of a tap networking device in
> > the host.
> > +It offers very good performance and can be configured to create
> > virtually
> > +any type of network topology. It requires configuration of that
> > network
> > +topology in the host and invoking QEMU as root unless the tap
> > device has been
> > +preconfigured to be owned by the user invoking qemu, or the
> > @option{f}d option is used
> 
> @option{fd}
> 
> Since you're discussing non-root tap setup, perhaps point to the
> helper
> option as well.
> 

Yeap, worth adding note.

> > +
> > +Valid options are:
> > +
> > +@table @option
> > +
> > +@item ifname=@var{name}
> > +Name of host tap device to be used by qemu.
> > +
> > +@item fd=@var{descriptor}
> > +File descriptor of an already opened tap.
> > +
> > +@item script=@var{scriptpath}
> > +Network script used to configure device.
> > +
> > +@item downscript=@var{scriptpath}
> > +Network script used to deconfigure device.
> > +
> > +@item sndbuf=@var{size}
> > +Limit for send buffer.
> > +
> > +@item vnet_hdr=on|off]
> > +Enable the IFF_VNET_HDR flag on the tap interface.
> > +
> > +@item vhost=[on|off]
> > +Enable vhost-net network accelerator.
> > +
> > +@item vhostfd=@var{descriptor}
> > +File descriptor of an already opened vhost-net device.
> > +
> > +@item vhostforce=[on|off]
> > +Force 'vhost=on' for non-MSIX virtio guests.
> > +
> > +@item helper=@var{helper}
> > +If running QEMU as an unprivileged user, use the network helper
> > +@var{helper} to configure the TAP interface. The default network
> > +helper executable is @file{/usr/local/libexec/qemu-bridge-helper}.
> 
> Should this be #ifdef CONFIG_NET_BRIDGE?
> 

As wrote before, this should be in ifdef even if it has no practical effect.

> > +
> > +@end table
> > +ETEXI
> > +#ifdef CONFIG_VDE
> > +STEXI
> > +@item -netdev vde
> > +
> > +Virtual Distributed Ethernet infrastructure is used. Unless you
> > specifically
> > +know that you want to use VDE, it is probably not the best backend
> > to use. This option
> > +is only available if QEMU has been compiled with vde support
> > enabled.
> > +
> > +Valid options are:
> > +
> > +@table @option
> > +
> > +@item sock=@var{socketpath}
> > +
> > +Path to the socket used for backend.
> > +
> > +@item port=@var{n}
> > +
> > +Port number.
> > +
> > +@item group=@var{groupname}
> > +
> > +Owner group for the used socket.
> > +
> > +@item mode=@var{octalmode}
> > +
> > +File permissions of used socket.
> > +
> > +@end table
> > +
> > +ETEXI
> > +#endif
> > +STEXI
> > +
> > +@item -netdev socket
> > +
> > +The socket networking backend allow you to create a network of
> > guests that can
> > +see each other. It's primarily useful in extending the network
> > created by slirp
> > +to multiple virtual machines.
> > +
> > +One of following options has to be specified:
> > +
> > +@table @option
> > +
> > +@item fd @var{descriptor}
> > +Qemu uses an already opened socket with file descriptor
> > @var{descriptor}
> > +
> > +@item listen [@var{hostname}]:@var{port}
> > +Specify port, and optionaly hostname, qemu will listen on.
> > +
> > +@item connect [@var{hostname}]:@var{port}
> > +Qemu connects to specified port and, optionaly, hostname.
> > +
> > +@item mcast @var{addr}
> > +Qemu uses UDP multicast address @var{addr}.
> > +
> > +@item udp @var{addr}:@var{port}
> > +Qemu uses UDP unicast address and port.
> > +
> > +@end table
> > +
> > +Option @option{localaddr}=@var{addr}:@var{port} can be used for
> > @option{mcast}
> > +and has to be used for @option{udp} option. It specifiy source
> > address and port
> > +for udp packets.
> > +
> > +ETEXI
> > +#ifdef CONFIG_NET_BRIDGE
> > +STEXI
> > +
> > +@item -netdev
> > bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
> > +Connect a host TAP network interface to a host bridge device. This
> > option is
> > +only available if QEMU has been compiled with net brdige support
> > enabled.
> 
> bridge
> 
> > +
> > +Valid options are:
> > +
> > +@table @option
> > +
> > +@item br=@var{bridge}
> > +Specify bridge TAP interface should be attached. Default value is
> > @file{br0}.
> > +
> > +@item helper=@var{helper}
> > +Network helper used to configure TAP inteface. Default helper is
> > +@file{/usr/local/libexec/qemu-bridge-helper}.
> > +
> > +@end table
> > +ETEXI
> > +#endif
> > +STEXI
> > +@end table
> > +@end table
> > +
> > +Following options for backend creation are obsolete but still
> > working:
> > +
> > +@table @option
> > +
> >  @item -net
> >  nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}]
> >  [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
> >  @findex -net
> >  Create a new Network Interface Card and connect it to VLAN @var{n}
> >  (@var{n}
> 


New version to be sent soon.

Mirek

Patch

diff --git a/qemu-options.hx b/qemu-options.hx
index b129996..a1d61b6 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1292,6 +1292,268 @@  DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
 #endif
     "socket],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL)
 STEXI
+@item -netdev user|tap|vde|socket,id=@var{str}[,option][,option][,...]
+
+Create a new network backend to the guest. The backend's @option{id} can be used with
+the @option{-device} option to connect a backend with a device, 
+e.g.
+
+@example
+-netdev user,id=mynet -device e1000,netdev=mynet
+@end example
+
+You can use following types of backend:
+
+@table @option
+
+@item -netdev user
+
+User networking is default network backend. This backend does not require root 
+priviledges, does not allow ICMP trafic and host is not directly accessible 
+from the host or the external network.
+
+Valid options are:
+
+@table @option
+
+@item restrict=y|yes|n|no
+If this options is enabled, the guest will be isolated, i.e. it will not be
+able to contact the host and no guest IP packets will be routed over the host
+to the outside. This option does not affect explicitly set forwarding rules.
+
+@item net=@var{addr}[/@var{mask}]
+Set the IP network address the guest will see. Optionally specify the netmask,
+either in the form a.b.c.d or as number of valid top-most bits. Default is
+10.0.2.0/8.
+
+@item host=@var{addr}
+Specify the guest-visible address of the host. Default is the 2nd IP in the
+guest network, i.e. x.x.x.2.
+
+@item hostname=@var{name}
+Specifies the client hostname reported by the builtin DHCP server.
+
+@item dhcpstart=@var{addr}
+Specify the first of the 16 IPs the built-in DHCP server can assign. Default
+is the 16th to 31st IP in the guest network, i.e. x.x.x.16 to x.x.x.31.
+
+@item dns=@var{addr}
+Specify the guest-visible address of the virtual nameserver. The address must
+be different from the host address. Default is the 3rd IP in the guest network,
+i.e. x.x.x.3.
+
+@item tftp=@var{dir}
+When using the user mode network stack, activate a built-in TFTP
+server. The files in @var{dir} will be exposed as the root of a TFTP server.
+The TFTP client on the guest must be configured in binary mode (use the command
+@code{bin} of the Unix TFTP client).
+
+@item bootfile=@var{file}
+When using the user mode network stack, broadcast @var{file} as the BOOTP
+filename. In conjunction with @option{tftp}, this can be used to network boot
+a guest from a local directory.
+
+Example (using pxelinux):
+@example
+qemu -hda linux.img -boot n -netdev user,id=netid,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
+@end example
+
+@item smb=@var{dir}[,smbserver=@var{addr}]
+When using the user mode network stack, activate a built-in SMB
+server so that Windows OSes can access to the host files in @file{@var{dir}}
+transparently. The IP address of the SMB server can be set to @var{addr}. By
+default the 4th IP in the guest network is used, i.e. x.x.x.4.
+
+In the guest Windows OS, the line:
+@example
+10.0.2.4 smbserver
+@end example
+must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
+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 in
+@file{/usr/sbin/smbd}. QEMU was tested successfully with smbd versions from
+Red Hat 9, Fedora Core 3 and OpenSUSE 11.x.
+
+@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
+the guest IP address @var{guestaddr} on guest port @var{guestport}. If
+@var{guestaddr} is not specified, its value is x.x.x.15 (default first address
+given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
+be bound to a specific host interface. If no connection type is set, TCP is
+used. This option can be given multiple times.
+
+For example, to redirect host X11 connection from screen 1 to guest
+screen 0, use the following:
+
+@example
+# on the host
+qemu -netdev user,id=netid,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
+# this host xterm should open in the guest X11 server
+xterm -display :1
+@end example
+
+To redirect telnet connections from host port 5555 to telnet port on
+the guest, use the following:
+
+@example
+# on the host
+qemu -netdev user,id=netid,hostfwd=tcp:5555::23 [...]
+telnet localhost 5555
+@end example
+
+Then when you use on the host @code{telnet localhost 5555}, you
+connect to the guest telnet server.
+
+@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
+Forward guest TCP connections to the IP address @var{server} on port @var{port}
+to the character device @var{dev}. This option can be given multiple times.
+
+@end table
+
+@item -netdev tap
+
+The tap networking backend makes use of a tap networking device in the host. 
+It offers very good performance and can be configured to create virtually 
+any type of network topology. It requires configuration of that network 
+topology in the host and invoking QEMU as root unless the tap device has been
+preconfigured to be owned by the user invoking qemu, or the @option{f}d option is used
+
+Valid options are:
+
+@table @option
+
+@item ifname=@var{name}
+Name of host tap device to be used by qemu. 
+
+@item fd=@var{descriptor}
+File descriptor of an already opened tap.
+
+@item script=@var{scriptpath}
+Network script used to configure device.
+
+@item downscript=@var{scriptpath}
+Network script used to deconfigure device.
+
+@item sndbuf=@var{size}
+Limit for send buffer.
+
+@item vnet_hdr=on|off]
+Enable the IFF_VNET_HDR flag on the tap interface.
+
+@item vhost=[on|off]
+Enable vhost-net network accelerator.
+
+@item vhostfd=@var{descriptor}
+File descriptor of an already opened vhost-net device.
+
+@item vhostforce=[on|off]
+Force 'vhost=on' for non-MSIX virtio guests.
+
+@item helper=@var{helper}
+If running QEMU as an unprivileged user, use the network helper
+@var{helper} to configure the TAP interface. The default network
+helper executable is @file{/usr/local/libexec/qemu-bridge-helper}.
+
+@end table
+ETEXI
+#ifdef CONFIG_VDE
+STEXI
+@item -netdev vde
+
+Virtual Distributed Ethernet infrastructure is used. Unless you specifically
+know that you want to use VDE, it is probably not the best backend to use. This option
+is only available if QEMU has been compiled with vde support enabled.
+
+Valid options are:
+
+@table @option
+
+@item sock=@var{socketpath}
+
+Path to the socket used for backend.
+
+@item port=@var{n}
+
+Port number.
+
+@item group=@var{groupname}
+
+Owner group for the used socket.
+
+@item mode=@var{octalmode}
+
+File permissions of used socket.
+
+@end table
+
+ETEXI
+#endif
+STEXI
+
+@item -netdev socket
+
+The socket networking backend allow you to create a network of guests that can
+see each other. It's primarily useful in extending the network created by slirp
+to multiple virtual machines. 
+
+One of following options has to be specified:
+
+@table @option
+
+@item fd @var{descriptor}
+Qemu uses an already opened socket with file descriptor @var{descriptor}
+
+@item listen [@var{hostname}]:@var{port}
+Specify port, and optionaly hostname, qemu will listen on.
+
+@item connect [@var{hostname}]:@var{port}
+Qemu connects to specified port and, optionaly, hostname.
+
+@item mcast @var{addr}
+Qemu uses UDP multicast address @var{addr}.
+
+@item udp @var{addr}:@var{port}
+Qemu uses UDP unicast address and port.
+
+@end table
+
+Option @option{localaddr}=@var{addr}:@var{port} can be used for @option{mcast}
+and has to be used for @option{udp} option. It specifiy source address and port 
+for udp packets.
+
+ETEXI
+#ifdef CONFIG_NET_BRIDGE
+STEXI
+
+@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
+Connect a host TAP network interface to a host bridge device. This option is
+only available if QEMU has been compiled with net brdige support enabled.
+
+Valid options are:
+
+@table @option
+
+@item br=@var{bridge}
+Specify bridge TAP interface should be attached. Default value is @file{br0}.
+
+@item helper=@var{helper}
+Network helper used to configure TAP inteface. Default helper is 
+@file{/usr/local/libexec/qemu-bridge-helper}.
+
+@end table
+ETEXI
+#endif
+STEXI
+@end table
+@end table
+
+Following options for backend creation are obsolete but still working:
+
+@table @option
+
 @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
 @findex -net
 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}