[libvirt] [PATCH] docs: document iface-* commands

[Eric Blake]

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

Dan was partially right:

> Though we will be wanting a followup patch for virsh.pod to add docs
> for this

but missed the fact that _none_ of the iface-* commands were
documented, so Laine's initial patch wasn't making the situation
any worse.  At any rate, this patch was heavily copy-and-pasted
from existing net-* commands.

 tools/virsh.c   |   12 ++++----
 tools/virsh.pod |   90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 95 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..4ef518f 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,94 @@ Convert a network name to network UUID.

 =back

+=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.
+
+=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.
+
+=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.
+
+=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>
+
+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.
+
+=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.
+
+=back
+
 =head1 STORAGE POOL COMMANDS

 The following commands manipulate storage pools. Libvirt has the
-- 
1.7.4.4