Message ID | 524d8e6b-3edf-4a78-8449-932d11bb2201@zmail17.collab.prod.int.phx2.redhat.com |
---|---|
State | New |
Headers | show |
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}
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
----- 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
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}
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: -----