Product SiteDocumentation Site

Chapter 7. Network Interfaces

7.1. Overview
7.2. XML Interface Description Format
7.3. Retrieving Information About Interfaces
7.3.1. Enumerating Interfaces
7.3.2. Obtaining a virInterface instance for an Interface
7.3.3. Retrieving Detailed Interface Information
7.3.4. Retrieving Interface Network Addresses
7.4. Managing interface configuration files
7.4.1. Defining an interface configuration
7.4.2. Undefining an interface configuration
7.4.3. changeRollback
7.4.4. changeBegin
7.4.5. changeCommit
7.5. Interface lifecycle management
7.5.1. Activating an interface
7.5.2. Deactivating an interface
This section covers the management of physical network interfaces using the libvirt virInterface class.

7.1. Overview

The configuration of network interfaces on physical hosts can be examined and modified with methods in the virInterface class. This is useful for setting up the host to share one physical interface between multiple guest domains you want connected directly to the network (briefly - enslave a physical interface to the bridge, then create a tap device for each VM you want to share the interface), as well as for general host network interface management. In addition to physical hardware, the methods can also be used to configure bridges, bonded interfaces, and vlan interfaces.
The virInterface class is not used to configure virtual networks (used to conceal the guest domain's interface behind a NAT); virtual networks are instead configured using the virNetwork class described in Chapter 6, Virtual Networks.
Each host interface is represented by an instance of the virInterface class and each of these has a single unique identifier:
The name method returns a string unique among all interfaces (active or inactive) on a host. This is the same string used by the operating system to identify the interface (eg: "eth0" or "br1").
Each interface object also has a second, non-unique index that can be duplicated in other interfaces on the same host:
The MACString method returns an ASCII string representation of the MAC address of this interface. Since multiple interfaces can share the same MAC address (for example, in the case of VLANs), this is not a unique identifier. However, it can still be used to search for an interface.
All interfaces configured with libvirt should be considered as persistent, since libvirt is actually changing the host's own persistent configuration data (usually contained in files somewhere under /etc), and not the interface itself.
When a new interface is defined (using the interfaceDefineXML method), or the configuration of an existing interface is changed (again, with interfaceDefineXML method), this configuration will be stored on the host. The live configuration of the interface itself will not be changed until the interface is restarted manually or the host is rebooted.