20.38. Interface Commands
The following commands manipulate host interfaces and as such should not be run from the guest virtual machine. These commands should be run from a terminal on the host physical machine.
The commands in this section are only supported if the machine has the NetworkManager service disabled, and is using the
Often, these host interfaces can then be used by name within guest virtual machine
<interface>elements (such as a system-created bridge interface), but there is no requirement that host interfaces be tied to any particular guest configuration XML at all. Many of the commands for host interfaces are similar to the ones used for guest virtual machines, and the way to name an interface is either by its name or its MAC address. However, using a MAC address for an
ifaceargument only works when that address is unique (if an interface and a bridge share the same MAC address, which is often the case, then using that MAC address results in an error due to ambiguity, and you must resort to a name instead).
20.38.1. Defining and Starting a Host Physical Machine Interface via an XML File
virsh iface-define filecommand define a host interface from an XML file. This command will only define the interface and will not start it.
virsh iface-define iface.xml
To start an interface which has already been defined, run
iface-start interface, where interface is the interface name.
20.38.2. Editing the XML Configuration File for the Host Interface
virsh iface-edit interfaceedits the XML configuration file for a host interface. This is the only recommended way to edit the XML configuration file. (For more information about these files, see Chapter 23, Manipulating the Domain XML.)
20.38.3. Listing Host Interfaces
virsh iface-listdisplays a list of active host interfaces. If
--allis specified, this list will also include interfaces that are defined but are inactive. If
--inactiveis specified only the inactive interfaces will be listed.
20.38.4. Converting a MAC Address into an Interface Name
virsh iface-name interfacecommand converts a host interface MAC address to an interface name, the provided MAC address is unique among the host’s interfaces. This command requires interface which is the interface's MAC address.
virsh iface-mac interfacecommand will convert a host's interface name to MAC address where in this case interface, is the interface name.
20.38.5. Stopping and Undefining a Specific Host Physical Machine Interface
virsh iface-destroy interfacecommand destroys (stops) a given host interface, which is the same as running
virsh if-downon the host. This command will disable that interface from active use and takes effect immediately.
To undefine the interface, use the
virsh iface-undefine interfacecommand along with the interface name.
20.38.6. Displaying the Host Configuration File
virsh iface-dumpxml interfacecommand displays the host interface information as an XML dump to stdout. If the
--inactiveargument is specified, then the output reflects the persistent state of the interface that will be used the next time it is started.
20.38.7. Creating Bridge Devices
virsh iface-bridgecommand creates a bridge device named bridge, and attaches the existing network device interface to the new bridge, which starts working immediately, with STP enabled and a delay of 0.
virsh iface-bridge interface bridge
Note that these settings can be altered with the
--no-startoption, and an number of seconds for delay. The IP address configuration of the interface will be moved to the new bridge device. For information on tearing down the bridge, see Section 20.38.8, “Tearing Down a Bridge Device”
20.38.8. Tearing Down a Bridge Device
virsh iface-unbridge bridgecommand tears down a specified bridge device named bridge, releases its underlying interface back to normal usage, and moves all IP address configuration from the bridge device to the underlying device. The underlying interface is restarted unless
--no-startargument is used, but keep in mind not restarting is generally not recommended. For the command to create a bridge, see Section 20.38.7, “Creating Bridge Devices”.
20.38.9. Manipulating Interface Snapshots
virsh iface-begincommand creates a snapshot of current host interface settings, which can later be committed (with
virsh iface-commit) or restored (
virsh iface-rollback). This is useful for situations where something fails when defining and starting a new host interface, and a system misconfiguration occurs. If a snapshot already exists, then this command will fail until the previous snapshot has been committed or restored. Undefined behavior will result if any external changes are made to host interfaces outside of the libvirt API between the time of the creation of a snapshot and its eventual commit or rollback.
virsh iface-commitcommand to declare all changes made since the last
virsh iface-beginas working, and then delete the rollback point. If no interface snapshot has already been started using
virsh iface-begin, then this command will fail.
virsh iface-rollbackto revert all host interface settings back to the state that recorded the last time the
virsh iface-begincommand was executed. If
virsh iface-begincommand had not been previously executed, then
virsh iface-rollbackwill fail. Note that if the host physical machine is rebooted before
virsh iface-commitis run, an automatic rollback will be performed which will restore the host's configuration to the state it was at the time that the
virsh iface-beginwas executed. This is useful in cases where an improper change to the network configuration renders the host unreachable for purposes of undoing the change, but the host is either power-cycled or otherwise forced to reboot.
Example 20.97. An example of working with snapshots
Define and start a new host interface.
virsh iface-define eth4-if.xml#
virsh if-start eth4
If something fails and the network stops running, roll back the changes.
If everything works properly, commit the changes.