From patchwork Sun Mar 4 07:39:34 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Miroslav Rezanina X-Patchwork-Id: 144480 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id 58B4BB6F9F for ; Sun, 4 Mar 2012 18:40:11 +1100 (EST) Received: from localhost ([::1]:51863 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1S4636-0002Gl-Rx for incoming@patchwork.ozlabs.org; Sun, 04 Mar 2012 02:40:08 -0500 Received: from eggs.gnu.org ([208.118.235.92]:55415) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1S462d-0002FO-W4 for qemu-devel@nongnu.org; Sun, 04 Mar 2012 02:40:00 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1S462b-0008M1-A2 for qemu-devel@nongnu.org; Sun, 04 Mar 2012 02:39:39 -0500 Received: from mx4-phx2.redhat.com ([209.132.183.25]:36718) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1S462a-0008Lv-Vd for qemu-devel@nongnu.org; Sun, 04 Mar 2012 02:39:37 -0500 Received: from zmail17.collab.prod.int.phx2.redhat.com (zmail17.collab.prod.int.phx2.redhat.com [10.5.83.19]) by mx4-phx2.redhat.com (8.13.8/8.13.8) with ESMTP id q247dZOP029603 for ; Sun, 4 Mar 2012 02:39:35 -0500 Date: Sun, 04 Mar 2012 02:39:34 -0500 (EST) From: Miroslav Rezanina To: qemu-devel@nongnu.org Message-ID: In-Reply-To: <687ceebb-7367-4c41-8d0c-feaae450050a@zmail17.collab.prod.int.phx2.redhat.com> MIME-Version: 1.0 X-Originating-IP: [10.36.112.16] X-Mailer: Zimbra 7.1.2_GA_3268 (ZimbraWebClient - SAF3 (Linux)/7.1.2_GA_3268) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 209.132.183.25 Subject: [Qemu-devel] [PATCH v2] Add -netdev to man page X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org 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. Signed-off-by: Miroslav Rezanina V2: - Fixed spelling errors - Fixed net and dhcpstart range values Patch: ----- diff --git a/qemu-options.hx b/qemu-options.hx index b129996..666fd58 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -1292,6 +1292,275 @@ 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. 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 +privileges, does not allow ICMP traffic, and guest is not directly accessible +from the host or the external network. + +Valid options are: + +@table @option + +@item restrict=on|off +If this option 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/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 15th to 30st IP in the guest network, i.e. x.x.x.15 to x.x.x.30. + +@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{fd} option is used (@option{helper} should be used when running as non-root user). + +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. + +ETEXI +#ifdef CONFIG_NET_BRIDGE +STEXI + +@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}. + +ETEXI +#endif +STEXI + +@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 bridge 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} @@ -1340,7 +1609,7 @@ 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 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. +is the 15th to 30st IP in the guest network, i.e. x.x.x.15 to x.x.x.30. @item dns=@var{addr} Specify the guest-visible address of the virtual nameserver. The address must