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

Tue May 31 20:21:40 UTC 2011

Thanks for taking care of this Eric. (Exactly how many do I owe you now? :-)

On 05/31/2011 03:51 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.
> ---
>
> 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

Not necessarily "to be used by virtual networks". They just manipulate 
host interfaces in general. Often those interfaces are not used by 
libvirt "virtual networks" at all, but referenced in a domain's 
<interface> element (eg a system-created bridge interface), or possibly 
not referenced within any libvirt config XML at all.

> +similar to the ones used for domains, and the way to name an interface
> +is either by its name or its MAC address.

Note that MAC address is not necessarily unique - multiple interfaces 
can have the same MAC address (and often do, for example a bridge could 
have the same MAC address as the NIC it's attached to)

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

Since MAC address isn't necessarily unique, if multiple interfaces are 
found with the same MAC address, this will return an error.

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

No confirmation is done. Confirmation is left to the application/human 
that is calling iface-commit.

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

No maybe about it - if iface-begin has been called, and you reboot 
without doing iface-commit or iface-rollback, then an implicit rollback 
will be done.

> +
> +=back
> +
>   =head1 STORAGE POOL COMMANDS
>
>   The following commands manipulate storage pools. Libvirt has the