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

Thu Jun 2 15:56:15 UTC 2011

On 05/31/2011 04:43 PM, Eric Blake wrote:
> 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,

As long as you're fixing this typo, how about changing "A lot" (which I 
consider too informal for written English) to "Many"?

>   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

Same thing - s/A lot/Many/

ACK with those two small nits fixed.

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