Re: [Qemu-devel] [PATCH] Add -netdev to man page

[Markus Armbruster]

Miroslav Rezanina <address@hidden> 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 <address@hidden>
>
> 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
> address@hidden -netdev 
> user|tap|vde|socket,address@hidden,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.
> +
> address@hidden
> +-netdev user,id=mynet -device e1000,netdev=mynet
> address@hidden example
> +
> +You can use following types of backend:
> +
> address@hidden @option
> +
> address@hidden -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:
> +
> address@hidden @option
> +
> address@hidden 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.
> +
> address@hidden address@hidden/@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).

> +
> address@hidden address@hidden
> +Specify the guest-visible address of the host. Default is the 2nd IP in the
> +guest network, i.e. x.x.x.2.
> +
> address@hidden address@hidden
> +Specifies the client hostname reported by the builtin DHCP server.
> +
> address@hidden address@hidden
> +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).

> address@hidden address@hidden
> +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.
> +
> address@hidden address@hidden
> +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
> address@hidden of the Unix TFTP client).
> +
> address@hidden address@hidden
> +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):
> address@hidden
> +qemu -hda linux.img -boot n -netdev 
> user,id=netid,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
> address@hidden example
> +
> address@hidden address@hidden,address@hidden
> +When using the user mode network stack, activate a built-in SMB
> +server so that Windows OSes can access to the host files in @address@hidden
> +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:
> address@hidden
> +10.0.2.4 smbserver
> address@hidden 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 @address@hidden can be accessed in @file{\\smbserver\qemu}.
> +
> +Note that a SAMBA server must be installed on the host OS in
> address@hidden/usr/sbin/smbd}. QEMU was tested successfully with smbd 
> versions from
> +Red Hat 9, Fedora Core 3 and OpenSUSE 11.x.
> +
> address@hidden 
> hostfwd=[tcp|udp]:address@hidden:@address@hidden:@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
> address@hidden 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:
> +
> address@hidden
> +# 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
> address@hidden example
> +
> +To redirect telnet connections from host port 5555 to telnet port on
> +the guest, use the following:
> +
> address@hidden
> +# on the host
> +qemu -netdev user,id=netid,hostfwd=tcp:5555::23 [...]
> +telnet localhost 5555
> address@hidden example
> +
> +Then when you use on the host @code{telnet localhost 5555}, you
> +connect to the guest telnet server.
> +
> address@hidden guestfwd=[tcp]:@var{server}:@address@hidden
> +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.
> +
> address@hidden table
> +
> address@hidden -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:
> +
> address@hidden @option
> +
> address@hidden address@hidden
> +Name of host tap device to be used by qemu. 
> +
> address@hidden address@hidden
> +File descriptor of an already opened tap.
> +
> address@hidden address@hidden
> +Network script used to configure device.
> +
> address@hidden address@hidden
> +Network script used to deconfigure device.
> +
> address@hidden address@hidden
> +Limit for send buffer.
> +
> address@hidden vnet_hdr=on|off]
> +Enable the IFF_VNET_HDR flag on the tap interface.
> +
> address@hidden vhost=[on|off]
> +Enable vhost-net network accelerator.
> +
> address@hidden address@hidden
> +File descriptor of an already opened vhost-net device.
> +
> address@hidden vhostforce=[on|off]
> +Force 'vhost=on' for non-MSIX virtio guests.
> +
> address@hidden address@hidden
> +If running QEMU as an unprivileged user, use the network helper
> address@hidden 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?

> +
> address@hidden table
> +ETEXI
> +#ifdef CONFIG_VDE
> +STEXI
> address@hidden -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:
> +
> address@hidden @option
> +
> address@hidden address@hidden
> +
> +Path to the socket used for backend.
> +
> address@hidden address@hidden
> +
> +Port number.
> +
> address@hidden address@hidden
> +
> +Owner group for the used socket.
> +
> address@hidden address@hidden
> +
> +File permissions of used socket.
> +
> address@hidden table
> +
> +ETEXI
> +#endif
> +STEXI
> +
> address@hidden -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:
> +
> address@hidden @option
> +
> address@hidden fd @var{descriptor}
> +Qemu uses an already opened socket with file descriptor @var{descriptor}
> +
> address@hidden listen address@hidden:@var{port}
> +Specify port, and optionaly hostname, qemu will listen on.
> +
> address@hidden connect address@hidden:@var{port}
> +Qemu connects to specified port and, optionaly, hostname.
> +
> address@hidden mcast @var{addr}
> +Qemu uses UDP multicast address @var{addr}.
> +
> address@hidden udp @var{addr}:@var{port}
> +Qemu uses UDP unicast address and port.
> +
> address@hidden table
> +
> +Option @address@hidden:@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
> +
> address@hidden -netdev bridge,address@hidden,address@hidden,address@hidden
> +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:
> +
> address@hidden @option
> +
> address@hidden address@hidden
> +Specify bridge TAP interface should be attached. Default value is @file{br0}.
> +
> address@hidden address@hidden
> +Network helper used to configure TAP inteface. Default helper is 
> address@hidden/usr/local/libexec/qemu-bridge-helper}.
> +
> address@hidden table
> +ETEXI
> +#endif
> +STEXI
> address@hidden table
> address@hidden table
> +
> +Following options for backend creation are obsolete but still working:
> +
> address@hidden @option
> +
>  @item -net nic[,address@hidden,address@hidden,address@hidden 
> [,address@hidden,address@hidden,address@hidden
>  @findex -net
>  Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}