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.
Warning
The commands in this section are only supported if the machine has the NetworkManager service disabled, and is using the
network service instead.
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 iface argument 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
The
virsh iface-define file command 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
The command
virsh iface-edit interface edits 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
The
virsh iface-list displays a list of active host interfaces. If --all is specified, this list will also include interfaces that are defined but are inactive. If --inactive is specified only the inactive interfaces will be listed.
20.38.4. Converting a MAC Address into an Interface Name
The
virsh iface-name interface command 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.
The
virsh iface-mac interface command 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
The
virsh iface-destroy interface command destroys (stops) a given host interface, which is the same as running virsh if-down on the host. This command will disable that interface from active use and takes effect immediately.
To undefine the interface, use the
virsh iface-undefine interface command along with the interface name.
20.38.6. Displaying the Host Configuration File
THe
virsh iface-dumpxml interface --inactive command displays the host interface information as an XML dump to stdout. If the --inactive argument 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
The
virsh iface-bridge command 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-stp option, --no-start option, 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
The
virsh iface-unbridge bridge --no-start command 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-start argument 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
The
virsh iface-begin command 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.
Use the
virsh iface-commit command to declare all changes made since the last virsh iface-begin as working, and then delete the rollback point. If no interface snapshot has already been started using virsh iface-begin, then this command will fail.
Use the
virsh iface-rollback to revert all host interface settings back to the state that recorded the last time the virsh iface-begin command was executed. If virsh iface-begin command had not been previously executed, then virsh iface-rollback will fail. Note that if the host physical machine is rebooted before virsh iface-commit is 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-begin was 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-begin#virsh iface-define eth4-if.xml#virsh if-start eth4
If something fails and the network stops running, roll back the changes.
# virsh iface-rollback
If everything works properly, commit the changes.
# virsh iface-commit