External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-07-12 12:55:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: document iface-* commands

Browse Source 
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.
This commit is contained in:
Eric Blake 2011-05-31 13:45:50 -06:00
parent 020342e68d
commit 72519f7331
2 changed files with 106 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
tools/virsh.c
View File

@ -11204,6 +11204,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,
@ -11218,16 +11222,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}
};

103
tools/virsh.pod
View File

@ -873,8 +873,8 @@ XML format for a device.
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,
see the documentation at L<http://libvirt.org/formatnetwork.html> . Many
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
@ -946,6 +946,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.
Many 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
@ -953,7 +1050,7 @@ capability to manage various storage solutions, including files, raw
partitions, and domain-specific formats, used to provide the storage
volumes visible as devices within virtual machines. For more detailed
information about this feature, see the documentation at
L<http://libvirt.org/formatstorage.html> . A lot of the commands for
L<http://libvirt.org/formatstorage.html> . Many of the commands for
pools are similar to the ones used for domains.
=over 4