qemu-doc: Rework the network options chapter to make "-net" less prominent

"-net" is clearly a legacy option. Yet we still use it in almost all
examples in the qemu documentation, and many other spots in the network
chapter. We should make it less prominent that users are not lured into
using it so often anymore. So instead of starting the network chapter with
"-net nic" and documenting "-net <backend>" below "-netdev <backend>"
everywhere, all the "-net" related documentation is now moved to the end
of the chapter. The new "-nic" option is moved to the beginning of the
chapter instead, with a new example that should demonstrate how "-nic"
can be used to shortcut "-device" with "-netdev". The examples in this
chapter are changed to use the "-device" and "-netdev" options or
"-nic" instead of "-net nic -net <backend>".

While we're at it, also remove a legacy remark about very old Linux
distributions. Also remove the "[...]" from the examples in this chapter
since we are not using this ellipsis in any other examples in our docu-
mentation.

Signed-off-by: Thomas Huth <thuth@redhat.com>
Signed-off-by: Jason Wang <jasowang@redhat.com>
This commit is contained in:
Thomas Huth 2018-03-12 13:20:50 +01:00 committed by Jason Wang
parent 47d3b60858
commit abbbb0350d
1 changed files with 94 additions and 95 deletions

View File

@ -2048,41 +2048,40 @@ DEF("net", HAS_ARG, QEMU_OPTION_net,
" old way to initialize a host network interface\n"
" (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
STEXI
@item -net nic[,vlan=@var{n}][,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
@findex -net
Configure or create an on-board (or machine default) Network Interface Card
(NIC) and connect it either to VLAN @var{n} (@var{n} = 0 is the default), or
to the netdev @var{nd}. The NIC is an e1000 by default on the PC
target. Optionally, the MAC address can be changed to @var{mac}, the
device address set to @var{addr} (PCI cards only),
and a @var{name} can be assigned for use in monitor commands.
Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
that the card should have; this option currently only affects virtio cards; set
@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
NIC is created. QEMU can emulate several different models of network card.
Valid values for @var{type} are
@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
Not all devices are supported on all targets. Use @code{-net nic,model=help}
for a list of available devices for your target.
@item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
@findex -nic
This option is a shortcut for configuring both the on-board (default) guest
NIC hardware and the host network backend in one go. The host backend options
are the same as with the corresponding @option{-netdev} options below.
The guest NIC model can be set with @option{model=@var{modelname}}.
Use @option{model=help} to list the available device types.
The hardware MAC address can be set with @option{mac=@var{macaddr}}.
The following two example do exactly the same, to show how @option{-nic} can
be used to shorten the command line length (note that the e1000 is the default
on i386, so the @option{model=e1000} parameter could even be omitted here, too):
@example
qemu-system-i386 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
qemu-system-i386 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
@end example
@item -nic none
Indicate that no network devices should be configured. It is used to override
the default configuration (default NIC with ``user'' host network backend)
which is activated if no other networking options are provided.
@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
@findex -netdev
@item -net user[,@var{option}][,@var{option}][,...]
Use the user mode network stack which requires no administrator
Configure user mode host network backend which requires no administrator
privilege to run. Valid options are:
@table @option
@item vlan=@var{n}
Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
@item id=@var{id}
@itemx name=@var{name}
Assign symbolic name for use in monitor commands.
@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must
be enabled. If neither is specified both protocols are enabled.
@item ipv4=on|off and ipv6=on|off
Specify that either IPv4 or IPv6 must be enabled. If neither is specified
both protocols are enabled.
@item net=@var{addr}[/@var{mask}]
Set IP network address the guest will see. Optionally specify the netmask,
@ -2134,7 +2133,7 @@ can not be resolved.
Example:
@example
qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...]
qemu-system-i386 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
@end example
@item tftp=@var{dir}
@ -2150,7 +2149,8 @@ a guest from a local directory.
Example (using pxelinux):
@example
qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
qemu-system-i386 -hda linux.img -boot n -device e1000,netdev=n1 \
-netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
@end example
@item smb=@var{dir}[,smbserver=@var{addr}]
@ -2169,8 +2169,6 @@ 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.
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
@ -2185,7 +2183,7 @@ screen 0, use the following:
@example
# on the host
qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
qemu-system-i386 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
# this host xterm should open in the guest X11 server
xterm -display :1
@end example
@ -2195,7 +2193,7 @@ the guest, use the following:
@example
# on the host
qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...]
qemu-system-i386 -nic user,hostfwd=tcp::5555-:23
telnet localhost 5555
@end example
@ -2214,7 +2212,7 @@ lifetime, like in the following example:
@example
# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
# the guest accesses it
qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...]
qemu-system-i386 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
@end example
Or you can execute a command on every TCP connection established by the guest,
@ -2223,7 +2221,7 @@ so that QEMU behaves similar to an inetd process for that virtual server:
@example
# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
# and connect the TCP stream to its stdin/stdout
qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
qemu-system-i386 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
@end example
@end table
@ -2234,8 +2232,7 @@ syntax gives undefined results. Their use for new applications is discouraged
as they will be removed from future versions.
@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
@itemx -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
Connect the host TAP network interface @var{name} to VLAN @var{n}.
Configure a host TAP network backend with ID @var{id}.
Use the network script @var{file} to configure it and the network script
@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
@ -2256,7 +2253,7 @@ Examples:
@example
#launch a QEMU instance with the default network script
qemu-system-i386 linux.img -net nic -net tap
qemu-system-i386 linux.img -nic tap
@end example
@example
@ -2270,12 +2267,11 @@ qemu-system-i386 linux.img \
@example
#launch a QEMU instance with the default network helper to
#connect a TAP device to bridge br0
qemu-system-i386 linux.img \
-net nic -net tap,"helper=/path/to/qemu-bridge-helper"
qemu-system-i386 linux.img -device virtio-net-pci,netdev=n1 \
-netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
@end example
@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
@itemx -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}]
Connect a host TAP network interface to a host bridge device.
Use the network helper @var{helper} to configure the TAP interface and
@ -2288,21 +2284,20 @@ Examples:
@example
#launch a QEMU instance with the default network helper to
#connect a TAP device to bridge br0
qemu-system-i386 linux.img -net bridge -net nic,model=virtio
qemu-system-i386 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
@end example
@example
#launch a QEMU instance with the default network helper to
#connect a TAP device to bridge qemubr0
qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio
qemu-system-i386 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
@end example
@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
machine using a TCP socket connection. If @option{listen} is
specified, QEMU waits for incoming connections on @var{port}
This host network backend can be used to connect the guest's network to
another QEMU virtual machine using a TCP socket connection. If @option{listen}
is specified, QEMU waits for incoming connections on @var{port}
(@var{host} is optional). @option{connect} is used to connect to
another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
specifies an already opened TCP socket.
@ -2311,21 +2306,19 @@ Example:
@example
# launch a first QEMU instance
qemu-system-i386 linux.img \
-net nic,macaddr=52:54:00:12:34:56 \
-net socket,listen=:1234
# connect the VLAN 0 of this instance to the VLAN 0
# of the first instance
-device e1000,netdev=n1,mac=52:54:00:12:34:56 \
-netdev socket,id=n1,listen=:1234
# connect the network of this instance to the network of the first instance
qemu-system-i386 linux.img \
-net nic,macaddr=52:54:00:12:34:57 \
-net socket,connect=127.0.0.1:1234
-device e1000,netdev=n2,mac=52:54:00:12:34:57 \
-netdev socket,id=n2,connect=127.0.0.1:1234
@end example
@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
Create a VLAN @var{n} shared with another QEMU virtual
machines using a UDP multicast socket, effectively making a bus for
every QEMU with same multicast address @var{maddr} and @var{port}.
Configure a socket host network backend to share the guest's network traffic
with another QEMU virtual machines using a UDP multicast socket, effectively
making a bus for every QEMU with same multicast address @var{maddr} and @var{port}.
NOTES:
@enumerate
@item
@ -2342,25 +2335,24 @@ Example:
@example
# launch one QEMU instance
qemu-system-i386 linux.img \
-net nic,macaddr=52:54:00:12:34:56 \
-net socket,mcast=230.0.0.1:1234
-device e1000,netdev=n1,mac=52:54:00:12:34:56 \
-netdev socket,id=n1,mcast=230.0.0.1:1234
# launch another QEMU instance on same "bus"
qemu-system-i386 linux.img \
-net nic,macaddr=52:54:00:12:34:57 \
-net socket,mcast=230.0.0.1:1234
-device e1000,netdev=n2,mac=52:54:00:12:34:57 \
-netdev socket,id=n2,mcast=230.0.0.1:1234
# launch yet another QEMU instance on same "bus"
qemu-system-i386 linux.img \
-net nic,macaddr=52:54:00:12:34:58 \
-net socket,mcast=230.0.0.1:1234
-device e1000,netdev=n3,macaddr=52:54:00:12:34:58 \
-netdev socket,id=n3,mcast=230.0.0.1:1234
@end example
Example (User Mode Linux compat.):
@example
# launch QEMU instance (note mcast address selected
# is UML's default)
# launch QEMU instance (note mcast address selected is UML's default)
qemu-system-i386 linux.img \
-net nic,macaddr=52:54:00:12:34:56 \
-net socket,mcast=239.192.168.1:1102
-device e1000,netdev=n1,mac=52:54:00:12:34:56 \
-netdev socket,id=n1,mcast=239.192.168.1:1102
# launch UML
/path/to/linux ubd0=/path/to/root_fs eth0=mcast
@end example
@ -2368,14 +2360,13 @@ qemu-system-i386 linux.img \
Example (send packets from host's 1.2.3.4):
@example
qemu-system-i386 linux.img \
-net nic,macaddr=52:54:00:12:34:56 \
-net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
-device e1000,netdev=n1,mac=52:54:00:12:34:56 \
-netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
@end example
@item -netdev l2tpv3,id=@var{id},src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}]
@itemx -net l2tpv3[,vlan=@var{n}][,name=@var{name}],src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}]
Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular
protocol to transport Ethernet (and other Layer 2) data frames between
Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a
popular protocol to transport Ethernet (and other Layer 2) data frames between
two systems. It is present in routers, firewalls and the Linux kernel
(from version 3.3 onwards).
@ -2428,14 +2419,13 @@ brctl addif br-lan vmtunnel0
# on 4.3.2.1
# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
qemu-system-i386 linux.img -net nic -net l2tpv3,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
qemu-system-i386 linux.img -device e1000,netdev=n1 \
-netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
@end example
@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
@itemx -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
Configure VDE backend to connect to PORT @var{n} of a vde switch running on host and
listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
and MODE @var{octalmode} to change default ownership and permissions for
communication port. This option is only available if QEMU has been compiled
@ -2446,19 +2436,9 @@ Example:
# launch vde switch
vde_switch -F -sock /tmp/myswitch
# launch QEMU instance
qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
qemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch
@end example
@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}]
Create a hub port on QEMU "vlan" @var{hubid}.
The hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single
netdev. @code{-net} and @code{-device} with parameter @option{vlan} create the
required hub automatically. Alternatively, you can also connect the hubport
to another netdev with ID @var{nd} by using the @option{netdev=@var{nd}}
option.
@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
@ -2477,17 +2457,36 @@ qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,sha
-device virtio-net-pci,netdev=net0
@end example
@item --nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr]
@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}]
This option is a shortcut for setting both, the on-board (default) guest NIC
hardware and the host network backend in one go. The host backend options are
the same as with the corresponding @option{--netdev} option. The guest NIC
hardware MAC address can be set with @option{mac=@var{macaddr}}.
Create a hub port on the emulated hub with ID @var{hubid}.
@item --nic none
Indicate that no network devices should be configured. It is used to override
the default configuration (default NIC with @option{--net user} backend) which
is activated if no other networking options are provided.
The hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a
single netdev. @code{-net} and @code{-device} with the parameter @option{vlan}
(deprecated), or @code{-nic hubport} can also be used to connect a
network device or a NIC to a hub. Alternatively, you can also connect the
hubport to another netdev with ID @var{nd} by using the @option{netdev=@var{nd}}
option.
@item -net nic[,vlan=@var{n}][,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
@findex -net
Legacy option to configure or create an on-board (or machine default) Network
Interface Card(NIC) and connect it either to the emulated hub port ("vlan")
with number @var{n} (@var{n} = 0 is the default), or to the netdev @var{nd}.
The NIC is an e1000 by default on the PC target. Optionally, the MAC address
can be changed to @var{mac}, the device address set to @var{addr} (PCI cards
only), and a @var{name} can be assigned for use in monitor commands.
Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
that the card should have; this option currently only affects virtio cards; set
@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
NIC is created. QEMU can emulate several different models of network card.
Use @code{-net nic,model=help} for a list of available devices for your target.
@item -net user|tap|bridge|socket|l2tpv3|vde[,...][,vlan=@var{n}][,name=@var{name}]
Configure a host network backend (with the options corresponding to the same
@option{-netdev} option) and connect it to the emulated hub ("vlan") with the
number @var{n} (default is number 0). Use @var{name} to specify the name of the
hub port.
ETEXI
STEXI