21.39. Managing Virtual Networks

This section covers managing virtual networks with the virsh command. To list virtual networks:
# virsh net-list
This command generates output similar to:
# virsh net-list
Name                 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>
Other virsh commands used in managing virtual networks are:
  • virsh net-autostart network-name : Marks a network-name to be started automatically when the libvirt daemon starts. The --disable option 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.

21.39.1. Autostarting a Virtual Network

The virsh net-autostart command configures a virtual network to be started automatically when the guest virtual machine boots.
# virsh net-autostart network [--disable]
This command accepts the --disable option, which disables the autostart command.

21.39.2. Creating a Virtual Network from an XML File

The virsh net-create command creates a virtual network from an XML file. To get a description of the XML network format used by libvirt, refer to 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

21.39.3. Defining a Virtual Network from an XML File

The virsh net-define command defines a virtual network from an XML file, the network is just defined but not instantiated.
# virsh net-define file

21.39.4. Stopping a Virtual Network

The virsh net-destroy command 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

21.39.5. Creating a Dump File

The virsh net-dumpxml command outputs the virtual network information as an XML dump to stdout for the specified virtual network. If --inactive is specified, physical functions are not expanded into their associated virtual functions.
# virsh net-dumpxml network [--inactive]

21.39.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.

21.39.7. Getting Information about a Virtual Network

The virsh net-info returns basic information about the network object.
# virsh net-info network

21.39.8. Listing Information about a Virtual Network

The virsh net-list command returns the list of active networks. If --all is specified this will also include defined but inactive networks. If --inactive is specified only the inactive ones will be listed. You may also want to filter the returned networks by --persistent to list the persistent ones, --transient to list the transient ones, --autostart to list the ones with autostart enabled, and --no-autostart to 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 [--inactive | --all] [--persistent] [<--transient>] [--autostart] [<--no-autostart>]

21.39.9. Converting a Network UUID to Network Name

The virsh net-name command converts a network UUID to network name.
# virsh net-name network-UUID

21.39.10. Converting a Network Name to Network UUID

The virsh net-uuid command converts a network name to network UUID.
# virsh net-uuid network-name

21.39.11. Starting a Previously Defined Inactive Network

The virsh net-start command starts a (previously defined) inactive network.
# virsh net-start network

21.39.12. Undefining the Configuration for an Inactive Network

The virsh net-undefine command undefines the configuration for an inactive network.
# virsh net-undefine network

21.39.13. Updating an Existing Network Definition File

# virsh net-update network directive section XML [--parent-index index] [[--live] [--config] | [--current]]
The virsh net-update command updates a specified section of an existing network definition by issuing one of the following directives to the section:
  • add-first
  • add-last or add (these are synonymous)
  • delete
  • modify
The section can be one of the following:
  • bridge
  • domain
  • ip
  • ip-dhcp-host
  • ip-dhcp-range
  • forward
  • forward interface
  • forward-pf
  • portgroup
  • dns-host
  • dns-txt
  • dns-srv
Each section is named by a concatenation of the XML element hierarchy leading to the element that is changed. For example, ip-dhcp-host changes a <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=’1.2.3.4’/>), 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-index option 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-index is given, that particular instance of <ip> will get the modification. If --live is specified, affect a running network. If --config is specified, affect the next startup of a persistent network. If --current is specified, affect the current network state. Both --live and --config flags may be given, but --current is exclusive. Not specifying any flag is the same as specifying --current.

21.39.14. Migrating Guest Virtual Machines with virsh

Information on migration using virsh is located in the section entitled Live KVM Migration with virsh Refer to Section 16.5, “Live KVM Migration with virsh”

21.39.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 "nat", "route", or no forwarding mode at all. This procedure will not work if the network has been configured with forward mode="bridge" or "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 refer to the documentation that is supplied with the server.

Procedure 21.5. Setting a static IP address

This procedure is performed on the host physical machine.
  1. Check the guest XML configuration file

    Display the guest's network configuration settings by running the virsh domiflist guest1 command. 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.
    # virsh domiflist guest1
    Interface  Type       Source     Model       MAC
    -------------------------------------------------------
    vnet4      network    default    virtio      52:54:00:48:27:1D
    
    
  2. Verify the DHCP range

    The 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 net-dumpxml default | egrep 'range|host\ mac'
    
    <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'/>
    
    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.
  3. Set a static IP address

    Use 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 --config
    The --live option allows this change to immediately take place and the --config option 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:00 for the first three digit pairs, and it is recommended to follow this convention.
  4. 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
    # sleep 10
    # virsh domif-setlink guest1 52:54:00:48:27:1D up
    This 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 sleep command 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 up command 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.