[libvirt] [PATCHv2] docs: document iface-* commands
Eric Blake
eblake at redhat.com
Tue May 31 20:43:04 UTC 2011
I intentionally set things up so 'virsh help interface' lists
commands in alphabetical order, but 'man virsh' lists them in
topical order; this matches our practice on some other commands.
* tools/virsh.pod: Document all iface commands.
* tools/virsh.c (ifaceCmds): Sort.
---
v2: fix points raised by Laine.
Interdiff from v1 before the actual patch:
=head1 INTERFACE COMMANDS
-The following commands manipulate host interfaces to be used by
-virtual networks. A lot of the commands for host interfaces are
-similar to the ones used for domains, and the way to name an interface
-is either by its name or its MAC address.
+The following commands manipulate host interfaces. Often, these host
+interfaces can then be used by name within domain <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.
+
+A lot of the commands for host interfaces are similar to the ones used
+for domains, and the way to name an interface is either by its name or
+its MAC address. However, using a MAC address for an I<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).
=over 4
@@ -985,7 +994,8 @@ I<--inactive> is specified only the inactive ones will be listed.
=item B<iface-name> I<iface-MAC>
-Convert a host interface MAC to interface name.
+Convert a host interface MAC to interface name, if the I<iface-MAC> is
+unique among the host's interfaces.
=item B<iface-name> I<iface-MAC>
@@ -993,7 +1003,7 @@ Convert a host interface name to MAC address.
=item B<iface-start> I<iface>
-Start a (previously defined) host interface.
+Start a (previously defined) host interface, such as by running "if-up".
=item B<iface-undefine> I<iface>
@@ -1011,17 +1021,16 @@ commit or rollback.
=item B<iface-commit>
-Confirm that all changes since the last I<iface-begin> are working,
-and delete the rollback point. If no interface snapshot has already
-been started, then this command will fail.
+Declare all changes since the last I<iface-begin> as working, and
+delete the rollback point. If no interface snapshot has already been
+started, then this command will fail.
=item B<iface-rollback>
Revert all host interface settings back to the state recorded in the
last I<iface-begin>. If no interface snapshot has already been
-started, then this command will fail. If appropriate netcf init
-scripts are also installed, then rebooting the host may serve as an
-implicit rollback point.
+started, then this command will fail. Rebooting the host also serves
+as an implicit rollback point.
=back
tools/virsh.c | 12 +++---
tools/virsh.pod | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
2 files changed, 104 insertions(+), 7 deletions(-)
diff --git a/tools/virsh.c b/tools/virsh.c
index dfd5bd2..b9f1101 100644
--- a/tools/virsh.c
+++ b/tools/virsh.c
@@ -11063,6 +11063,10 @@ static const vshCmdDef nodedevCmds[] = {
};
static const vshCmdDef ifaceCmds[] = {
+ {"iface-begin", cmdInterfaceBegin, opts_interface_begin,
+ info_interface_begin, 0},
+ {"iface-commit", cmdInterfaceCommit, opts_interface_commit,
+ info_interface_commit, 0},
{"iface-define", cmdInterfaceDefine, opts_interface_define,
info_interface_define, 0},
{"iface-destroy", cmdInterfaceDestroy, opts_interface_destroy,
@@ -11077,16 +11081,12 @@ static const vshCmdDef ifaceCmds[] = {
info_interface_mac, 0},
{"iface-name", cmdInterfaceName, opts_interface_name,
info_interface_name, 0},
+ {"iface-rollback", cmdInterfaceRollback, opts_interface_rollback,
+ info_interface_rollback, 0},
{"iface-start", cmdInterfaceStart, opts_interface_start,
info_interface_start, 0},
{"iface-undefine", cmdInterfaceUndefine, opts_interface_undefine,
info_interface_undefine, 0},
- {"iface-begin", cmdInterfaceBegin, opts_interface_begin,
- info_interface_begin, 0},
- {"iface-commit", cmdInterfaceCommit, opts_interface_commit,
- info_interface_commit, 0},
- {"iface-rollback", cmdInterfaceRollback, opts_interface_rollback,
- info_interface_rollback, 0},
{NULL, NULL, NULL, NULL, 0}
};
diff --git a/tools/virsh.pod b/tools/virsh.pod
index 9251db6..ae0c887 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -865,7 +865,7 @@ The following commands manipulate networks. 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 L<http://libvirt.org/formatnetwork.html> . A lot
-of the command for virtual networks are similar to the one used for domains,
+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.
=over 4
@@ -937,6 +937,103 @@ Convert a network name to network UUID.
=back
+=head1 INTERFACE COMMANDS
+
+The following commands manipulate host interfaces. Often, these host
+interfaces can then be used by name within domain <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.
+
+A lot of the commands for host interfaces are similar to the ones used
+for domains, and the way to name an interface is either by its name or
+its MAC address. However, using a MAC address for an I<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).
+
+=over 4
+
+=item B<iface-define> I<file>
+
+Define a host interface from an XML I<file>, the interface is just defined but
+not started.
+
+=item B<iface-destroy> I<interface>
+
+Destroy a given host interface, such as by running "if-down" to
+disable that interface from active use. This takes effect immediately.
+
+=item B<iface-dumpxml> I<interface> optional I<--inactive>
+
+Output the host interface information as an XML dump to stdout. If
+I<--inactive> is specified, then the output reflects the persistent
+state of the interface that will be used the next time it is started.
+
+=item B<iface-edit> I<interface>
+
+Edit the XML configuration file for a host interface.
+
+This is equivalent to:
+
+ virsh iface-dumpxml iface > iface.xml
+ vi iface.xml (or make changes with your other text editor)
+ virsh iface-define iface.xml
+
+except that it does some error checking.
+
+The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
+variables, and defaults to C<vi>.
+
+=item B<iface-list> optional I<--inactive> or I<--all>
+
+Returns the list of active host interfaces. If I<--all> is specified
+this will also include defined but inactive interfaces. If
+I<--inactive> is specified only the inactive ones will be listed.
+
+=item B<iface-name> I<iface-MAC>
+
+Convert a host interface MAC to interface name, if the I<iface-MAC> is
+unique among the host's interfaces.
+
+=item B<iface-name> I<iface-MAC>
+
+Convert a host interface name to MAC address.
+
+=item B<iface-start> I<iface>
+
+Start a (previously defined) host interface, such as by running "if-up".
+
+=item B<iface-undefine> I<iface>
+
+Undefine the configuration for an inactive host interface.
+
+=item B<iface-begin>
+
+Create a snapshot of current host interface settings, which can later
+be committed (I<iface-commit>) or restored (I<iface-rollback>). If a
+snapshot already exists, then this command will fail until the
+previous snapshot has been committed or restored. Undefined behavior
+results if any external changes are made to host interfaces outside of
+the libvirt API between the beginning of a snapshot and its eventual
+commit or rollback.
+
+=item B<iface-commit>
+
+Declare all changes since the last I<iface-begin> as working, and
+delete the rollback point. If no interface snapshot has already been
+started, then this command will fail.
+
+=item B<iface-rollback>
+
+Revert all host interface settings back to the state recorded in the
+last I<iface-begin>. If no interface snapshot has already been
+started, then this command will fail. Rebooting the host also serves
+as an implicit rollback point.
+
+=back
+
=head1 STORAGE POOL COMMANDS
The following commands manipulate storage pools. Libvirt has the
--
1.7.4.4
More information about the libvir-list
mailing list