Show Table of Contents
20.37. Managing Virtual Networks
This section covers managing virtual networks with the
virshcommand. To list virtual networks:
This command generates output similar to:
virsh net-listName State Autostart ----------------------------------------- default active yes vnet1 active yes vnet2 active yes
To view network information for a specific virtual network:
virsh net-dumpxml NetworkName
This displays information about a specified virtual network in XML format:
virsh net-dumpxml vnet1<network> <name>vnet1</name> <uuid>98361b46-1581-acb7-1643-85a412626e70</uuid> <forward dev='eth0'/> <bridge name='vnet0' stp='on' forwardDelay='0' /> <ip address='192.168.100.1' netmask='255.255.255.0'> <dhcp> <range start='192.168.100.128' end='192.168.100.254' /> </dhcp> </ip> </network>
virshcommands used in managing virtual networks are:
virsh net-autostart network-name: Marks a network-name to be started automatically when the
libvirtdaemon starts. The
--disableoption un-marks the network-name.
virsh net-create XMLfile: Starts a new (transient) network using an XML definition from an existing file.
virsh net-define XMLfile: Defines a new network using an XML definition from an existing file without starting it.
virsh net-destroy network-name: Destroys a network specified as network-name.
virsh net-name networkUUID: Converts a specified networkUUID to a network name.
virsh net-uuid network-name: Converts a specified network-name to a network UUID.
virsh net-start nameOfInactiveNetwork: Starts an inactive network.
virsh net-undefine nameOfInactiveNetwork: Removes the inactive XML definition of a network. This has no effect on the network state. If the domain is running when this command is executed, the network continues running. However, the network becomes transient instead of persistent.
libvirt has the capability to define virtual networks which can then be used by domains and linked to actual network devices. For more detailed information about this feature see the documentation at libvirt upstream website . Many of the commands for virtual networks are similar to the ones used for domains, but the way to name a virtual network is either by its name or UUID.
20.37.1. Autostarting a Virtual Network
virsh net-autostartcommand configures a virtual network to be started automatically when the guest virtual machine boots.
# virsh net-autostart network [
This command accepts the
--disableoption, which disables the autostart command.
20.37.2. Creating a Virtual Network from an XML File
virsh net-createcommand creates a virtual network from an XML file. To get a description of the XML network format used by libvirt, see the libvirt upstream website. In this command file is the path to the XML file. To create the virtual network from an XML file, run:
virsh net-create file
20.37.3. Defining a Virtual Network from an XML File
virsh net-definecommand defines a virtual network from an XML file, the network is just defined but not instantiated.
virsh net-define file
20.37.4. Stopping a Virtual Network
virsh net-destroycommand destroys (stops) a given virtual network specified by its name or UUID. This takes effect immediately. To stop the specified network network is required.
virsh net-destroy network
20.37.5. Creating a Dump File
virsh net-dumpxmlcommand outputs the virtual network information as an XML dump to stdout for the specified virtual network. If
--inactiveis specified, physical functions are not expanded into their associated virtual functions.
virsh net-dumpxml network [
20.37.6. Editing a Virtual Network's XML Configuration File
The following command edits the XML configuration file for a network:
virsh net-edit network
The editor used for editing the XML file can be supplied by the $VISUAL or $EDITOR environment variables, and defaults to vi.
20.37.7. Getting Information about a Virtual Network
virsh net-inforeturns basic information about the network object.
virsh net-info network
20.37.8. Listing Information about a Virtual Network
virsh net-listcommand returns the list of active networks. If
--allis specified this will also include defined but inactive networks. If
--inactiveis specified only the inactive ones will be listed. You may also want to filter the returned networks by
--persistentto list the persistent ones,
--transientto list the transient ones,
--autostartto list the ones with autostart enabled, and
--no-autostartto list the ones with autostart disabled.
Note: When talking to older servers, this command is forced to use a series of API calls with an inherent race, where a pool might not be listed or might appear more than once if it changed state between calls while the list was being collected. Newer servers do not have this problem.
To list the virtual networks, run:
virsh net-list [
--transient>] [--autostart] [<
20.37.9. Converting a Network UUID to Network Name
virsh net-namecommand converts a network UUID to network name.
virsh net-name network-UUID
20.37.10. Converting a Network Name to Network UUID
virsh net-uuidcommand converts a network name to network UUID.
virsh net-uuid network-name
20.37.11. Starting a Previously Defined Inactive Network
virsh net-startcommand starts a (previously defined) inactive network.
virsh net-start network
20.37.12. Undefining the Configuration for an Inactive Network
virsh net-undefinecommand undefines the configuration for an inactive network.
virsh net-undefine network
20.37.13. Updating an Existing Network Definition File
virsh net-update network directive section XML
virsh net-updatecommand updates a specified section of an existing network definition by issuing one of the following directives to the section:
add(these are synonymous)
The section can be one of the following:
Each section is named by a concatenation of the XML element hierarchy leading to the element that is changed. For example,
<host>element that is contained inside a
<dhcp>element inside an
<ip>element of the network.
XML is either the text of a complete XML element of the type being changed (for instance,
<host mac="00:11:22:33:44:55’ ip=’18.104.22.168’/>), or the name of a file that contains a complete XML element. Disambiguation is done by looking at the first character of the provided text - if the first character is
<, it is XML text, if the first character is not
>, it is the name of a file that contains the xml text to be used. The
--parent-indexoption is used to specify which of several parent elements the requested element is in (0-based).
For example, a dhcp
<host>element could be in any one of multiple
<ip>elements in the network; if a parent-index is not provided, the most appropriate
<ip>element will be selected (usually the only one that already has a
<dhcp>element), but if
--parent-indexis given, that particular instance of
<ip>will get the modification. If
--liveis specified, affect a running network. If
--configis specified, affect the next startup of a persistent network. If
--currentis specified, affect the current network state. Both
--configflags may be given, but
--currentis exclusive. Not specifying any flag is the same as specifying
20.37.14. Migrating Guest Virtual Machines with virsh
Information on migration using virsh is located in the section entitled Live KVM Migration with virsh See Section 15.5, “Live KVM Migration with virsh”
20.37.15. Setting a Static IP Address for the Guest Virtual Machine
In cases where a guest virtual machine is configured to acquire its IP address from DHCP, but you still need it to have a predictable static IP address, you can use the following procedure to modify the DHCP server configuration used by libvirt. This procedure requires that you know the MAC address of the guest interface in order to make this change. Therefore, you will need to perform the operation after the guest has been created, or decide on a MAC address for the guest prior to creating it, and then set this same address manually when creating the guest virtual machine.
In addition, you should note that this procedure only works for guest interfaces that are connected to a libvirt virtual network with a forwarding mode of
"route", or no forwarding mode at all. This procedure will not work if the network has been configured with
"hostdev". In those cases, the DCHP server is located elsewhere on the network, and is therefore not under control of libvirt. In this case the static IP entry would need to be made on the remote DHCP server. To do that see the documentation that is supplied with the server.
Procedure 20.5. Setting a static IP address
This procedure is performed on the host physical machine.
Check the guest XML configuration fileDisplay the guest's network configuration settings by running the
virsh domiflist guest1command. Substitute the name of your virtual machine in place of guest1. A table is displayed. Look in the Source column. That is the name of your network. In this example the network is called default. This name will be used for the rest of the procedure as well as the MAC address.
virshInterface Type Source Model MAC ------------------------------------------------------- vnet4 network default virtio 52:54:00:48:27:1D
Verify the DHCP rangeThe IP address that you set must be within the dhcp range that is specified for the network. In addition, it must also not conflict with any other existing static IP addresses on the network. To check the range of addresses available as well as addresses used, use the following command on the host machine:
virsh<range start='198.51.100.2' end='198.51.100.254'/> <host mac='52:54:00:48:27:1C:1D' ip='198.51.100.2'/>
net-dumpxml default | egrep 'range|host\ mac'The output you see will differ from the example and you may see more lines and multiple host mac lines. Each guest static IP address will have one line.
Set a static IP addressUse the following command on the host machine, and replace default with the name of the network.
virsh net-update default add ip-dhcp-host '<host mac="52:54:00:48:27:1D" ip="198.51.100.3"/>' --live --configThe
--liveoption allows this change to immediately take place and the
--configoption makes the change persistent. This command will also work for guest virtual machines that you have not yet created as long as you use a valid IP and MAC address. The MAC address should be a valid unicast MAC address (6 hexadecimal digit pairs separated by
:, with the first digit pair being an even number); when libvirt creates a new random MAC address, it uses
52:54:00for the first three digit pairs, and it is recommended to follow this convention.
Restart the interface (optional)If the guest virtual machine is currently running, you will need to force the guest virtual machine to re-request a DHCP address. If the guest is not running, the new IP address will be implemented the next time you start it. To restart the interface, enter the following commands on the host machine:
virsh domif-setlink guest1 52:54:00:48:27:1D down#
virsh domif-setlink guest1 52:54:00:48:27:1D upThis command makes the guest virtual machine's operating system think that the Ethernet cable has been unplugged, and then re-plugged after ten seconds. The
sleepcommand is important because many DHCP clients allow for a short disconnect of the cable without re-requesting the IP address. Ten seconds is long enough so that the DHCP client forgets the old IP address and will request a new one once the
upcommand is executed. If for some reason this command fails, you will have to reset the guest's interface from the guest operating system's management interface.