[libvirt] [PATCH v2 9/9] virt-admin: Provide a man page for virt-admin

Wed Nov 4 07:55:26 UTC 2015

On Fri, Oct 16, 2015 at 08:12:26PM +0200, Erik Skultety wrote:
>---
> tools/Makefile.am    |   8 +-
> tools/virt-admin.pod | 278 +++++++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 285 insertions(+), 1 deletion(-)
> create mode 100644 tools/virt-admin.pod
>
>diff --git a/tools/Makefile.am b/tools/Makefile.am
>index e68fe84..d8cc1e7 100644
>--- a/tools/Makefile.am
>+++ b/tools/Makefile.am
>@@ -83,7 +83,8 @@ dist_man1_MANS = \
> 		virt-host-validate.1 \
> 		virt-pki-validate.1 \
> 		virt-xml-validate.1 \
>-		virsh.1
>+		virsh.1 \
>+		virt-admin.1
> if WITH_LXC
> dist_man1_MANS += virt-login-shell.1
> else ! WITH_LXC
>@@ -292,6 +293,11 @@ virsh.1: virsh.pod $(top_srcdir)/configure.ac
> 	    && if grep 'POD ERROR' $(srcdir)/$@ ; then \
> 		rm $(srcdir)/$@; exit 1; fi
>
>+virt-admin.1: virt-admin.pod $(top_srcdir)/configure.ac
>+	$(AM_V_GEN)$(POD2MAN) $< $(srcdir)/$@ \
>+	    && if grep 'POD ERROR' $(srcdir)/$@ ; then \
>+		rm $(srcdir)/$@; exit 1; fi
>+

If you do s/virt-admin/%, then you can make it a general rule and
clean up the makefile a little bit.

> install-data-local: install-init install-systemd
>
> uninstall-local: uninstall-init uninstall-systemd
>diff --git a/tools/virt-admin.pod b/tools/virt-admin.pod
>new file mode 100644
>index 0000000..f08dfc5
>--- /dev/null
>+++ b/tools/virt-admin.pod
>@@ -0,0 +1,278 @@
>+=head1 NAME
>+
>+virt-admin - virtualization daemon administrating user interface
>+

This reads weirdly.  I would say either "user interface for daemon
administration" or "daemon administration interface" or something
similar.

>+=head1 SYNOPSIS
>+
>+B<virt-admin> [I<OPTION>]... [I<COMMAND_STRING>]
>+
>+B<virt-admin> [I<OPTION>]... I<COMMAND> [I<ARG>]...
>+
>+=head1 DESCRIPTION
>+
>+The B<virt-admin> program is the main administrating interface to modify/tweak

Modify and tweak have the same meaning here.

>+the libvirt daemon configuration as well as to monitor and manage all clients

Not only libvirt, it will be enabled for other daemons as well.  And
it will do more, how about abstracting it a bit, e.g.:

The B<virt-admin> program is the main administrating interface for
modifying daemon configuration in runtime as well as monitoring and
changing daemon behaviour.

or something along those lines.

>+connected to the daemon.
>+
>+The basic structure of most virt-admin usage is:
>+
>+  virt-admin [OPTION]... <command> [ARG]...
>+
>+Where I<command> is one of the commands listed below.
>+
>+The B<virt-admin> program can be used either to run one I<COMMAND> by giving the
>+command and its arguments on the shell command line, or a I<COMMAND_STRING>
>+which is a single shell argument consisting of multiple I<COMMAND> actions
>+and their arguments joined with whitespace, and separated by semicolons
>+between commands.  Within I<COMMAND_STRING>, virt-admin understands the
>+same single, double, and backslash escapes as the shell, although you must
>+add another layer of shell escaping in creating the single shell argument.
>+If no command is given in the command line, B<virt-admin> will then start a minimal
>+interpreter waiting for your commands, and the B<quit> command will then exit
>+the program.
>+
>+The B<virt-admin> program understands the following I<OPTIONS>.
>+
>+=over 4
>+
>+=item B<-c>, B<--connect> I<URI>
>+
>+Connect to the specified I<URI>, as if by the B<connect> command,
>+instead of the default connection.
>+
>+=item B<-d>, B<--debug> I<LEVEL>
>+
>+Enable debug messages at integer I<LEVEL> and above.  I<LEVEL> can
>+range from 0 to 4 (default).  See the documentation of B<VIRSH_DEBUG>

s/VIRSH_DEBUG/VIRT_ADMIN_DEBUG/

and also add that info here (copy-paste with name changes from
virsh.pod is fine)

>+environment variable below for the description of each I<LEVEL>.
>+
>+=item B<-h>, B<--help>
>+
>+Ignore all other arguments, and behave as if the B<help> command were
>+given instead.
>+

While on this, I've found out that if I run 'virt-admin -h' it errors
out with:

error: option '-h'/'--help' requires an argument

but 'virt-admin --help' works fine.

>+=item B<-l>, B<--log> I<FILE>
>+
>+Output logging details to I<FILE>.
>+
>+=item B<-q>, B<--quiet>
>+
>+Avoid extra informational messages.
>+

One of these "extra informational messages" is newline after any
command.  It can be seen clearly with 'echo asdf' run in virt-admin
-q and without -q :)

Unfortunately, virsh does that too.

>+=item B<-v>, B<--version[=short]>
>+
>+Ignore all other arguments, and prints the version of the libvirt library
>+virt-admin is coming from
>+
>+=item B<-V>, B<--version=long>
>+
>+Ignore all other arguments, and prints the version of the libvirt library
>+virt-admin is coming from.
>+
>+=back
>+
>+=head1 NOTES
>+
>+Due to still limited capabilities of libvirt-admin library is usage of
>+B<virt-admin> tool, which is under continuous development, currently meant as
>+a feature preview only and its capabilities are very constrained at the moment,
>+comprising from connection establishment and generic commands only. Also note
>+that with upcoming features/commands, no backwards compatibility can be
>+guaranteed yet, since B<virt-admin> relies on I<libvirt-admin> library where
>+it's also not guaranteed that the public APIs won't change over the first
>+several releases.
>+

Although this is nice to say, I don't think we can do that.  From the
point when we enable it, it must be backward compatible.  We can break
compatibility only until we remove that ' && false'.

>+Most B<virt-admin> operations rely upon the I<libvirt-admin> library being able
>+to connect to an already running libvirtd service. This can usually be done
>+using the command B<service libvirtd start>.
>+

I would either mention other services since it can be said to connect
somewhere else.  Or not mention this at all.  If people run this
command, they most probably have daemon running and want to do
something to it.

>+Running B<virt-admin> requires root privileges due to the
>+communications channels used to talk to the daemon. An exempt to this rule would
>+be adding user to a group with write permission to the admin socket.
>+

I wouldn't mention the group privilege, or add something similar to
what's mentioned before the unix_sock_admin_perms config option.

>+=head1 GENERIC COMMANDS
>+
>+The following commands are generic.
>+
>+=over 4
>+
>+=item B<help> [I<command-or-group>]
>+
>+This lists each of the virt-admin commands.  When used without options, all
>+commands are listed, one per line, grouped into related categories,
>+displaying the keyword for each group.
>+
>+To display detailed information for a specific command, use its name as the
>+option.
>+
>+=item B<quit>, B<exit>
>+
>+quit this interactive terminal
>+
>+=item B<version>
>+
>+Will print out the major version info about which libvirt library was this

We also print out minor and micro version.

>+client built from. As opposed to I<virsh> client, the output already includes
>+the version of the libvirt daemon.
>+

not necessarily libvirt, also I would not completely error out when
connection to daemon cannot be established.  Also we throw too many
errors in that case, look at it:

error: Failed to connect to the admin server
error: no valid connection
error: Failed to connect socket to '/var/run/libvirt/libvirt-admin-sock': No such file or directory

That's pretty confusing for the user, well, mainly for users who don't
read their error messages if they have more than one line =D  We
should clear up the vshError() calls.

My reasoning for this is that we might ask someone for the version
info and use that for debugging, so the more we can print the better,
but even something small can help.

>+B<Example>
>+
>+ $ virt-admin version
>+ Compiled against library: libvirt 1.2.21
>+ Using library: libvirt 1.2.21
>+ Running against daemon: 1.2.20
>+
>+=item B<cd> [I<directory>]
>+
>+Will change current directory to I<directory>.  The default directory
>+for the B<cd> command is the home directory or, if there is no I<HOME>
>+variable in the environment, the root directory.
>+
>+This command is only available in interactive mode.
>+
>+=item B<pwd>
>+
>+Will print the current directory.
>+
>+=item B<connect> [I<URI>]
>+
>+(Re)-Connect to a daemon's administrating server. The I<URI> parameter
>+specifies how to connect to the administrating server. Currently, only
>+connection to libvirtd admin server is supported.

These are all the things we will have to go through and clean up later
after we turn it on for other daemons.

>+If I<LIBVIRT_ADMIN_DEFAULT_URI> or I<default-admin-uri> (see below) were set,
>+I<connect> is automatically issued every time a command that requires an
>+active connection is executed. Note that this only applies if there is no
>+connection at all or there is an inactive one.
>+
>+To find the currently used URI, check the I<uri> command documented below.
>+
>+For remote access see the documentation page at
>+L<http://libvirt.org/uri.html> on how to make URIs.
>+
>+=item B<uri>
>+
>+Prints the administrating server canonical URI, can be useful in shell mode. If
>+no I<uri> was specified, neither I<LIBVIRT_ADMIN_DEFAULT_URI> or
>+I<default-admin-uri> were set, libvirtd:///system is used.
>+
>+=back
>+
>+=head1 ENVIRONMENT
>+
>+The following environment variables can be set to alter the behaviour
>+of C<virt-admin>
>+
>+=over 4
>+
>+=item VIRT_ADMIN_DEBUG=<0 to 4>
>+
>+Turn on verbose debugging of virt-admin commands. Valid levels are
>+
>+=over 4
>+
>+=item * VIRT_ADMIN_DEBUG=0
>+
>+DEBUG - Messages at ALL levels get logged
>+
>+=item * VIRT_ADMIN_DEBUG=1
>+
>+INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
>+
>+=item * VIRT_ADMIN_DEBUG=2
>+
>+NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
>+
>+=item * VIRT_ADMIN_DEBUG=3
>+
>+WARNING - Logs messages at levels WARNING and ERROR
>+
>+=item * VIRT_ADMIN_DEBUG=4
>+
>+ERROR - Messages at only ERROR level gets logged.
>+
>+=back
>+
>+=item VIRT_ADMIN_LOG_FILE=C<LOGFILE>
>+
>+The file to log virt-admin debug messages.
>+
>+=item LIBVIRT_ADMIN_DEFAULT_URI
>+
>+The daemon whose admin server to connect to by default. Set this to a URI, in
>+the same format as accepted by the B<connect> option. This overrides the
>+default URI set in any client config file.
>+
>+=item VISUAL
>+
>+The editor to use by the B<edit> and related options.
>+

there is no edit option, and we don't know if there will be, just
generelize it (like it will be used when running an editor will be
needed or something

>+=item EDITOR
>+
>+The editor to use by the B<edit> and related options, if C<VISUAL>
>+is not set.
>+
>+=item VIRT_ADMIN_HISTSIZE
>+
>+The number of commands to remember in the command  history.  The
>+default value is 500.
>+
>+=item LIBVIRT_DEBUG=LEVEL
>+
>+Turn on verbose debugging of all libvirt API calls. Valid levels are
>+
>+=over 4
>+
>+=item * LIBVIRT_DEBUG=1
>+
>+Messages at level DEBUG or above
>+
>+=item * LIBVIRT_DEBUG=2
>+
>+Messages at level INFO or above
>+
>+=item * LIBVIRT_DEBUG=3
>+
>+Messages at level WARNING or above
>+
>+=item * LIBVIRT_DEBUG=4
>+
>+Messages at level ERROR or above
>+
>+=back
>+
>+For further information about debugging options consult C<http://libvirt.org/logging.html>
>+
>+=back
>+
>+=head1 BUGS
>+
>+Report any bugs discovered to the libvirt community via the mailing
>+list C<http://libvirt.org/contact.html> or bug tracker C<http://libvirt.org/bugs.html>.
>+Alternatively report bugs to your software distributor / vendor.
>+
>+=head1 AUTHORS
>+
>+  Please refer to the AUTHORS file distributed with libvirt.
>+
>+  Based on the xm man page by:
>+  Sean Dague <sean at dague dot net>
>+  Daniel Stekloff <dsteklof at us dot ibm dot com>
>+

This is more probably based on the virsh man page, but that's just my
guess ;)

>+=head1 COPYRIGHT
>+
>+Copyright (C) 2015 Red Hat, Inc., and the authors listed in the
>+libvirt AUTHORS file.
>+
>+=head1 LICENSE
>+
>+virt-admin is distributed under the terms of the GNU LGPL v2+.
>+This is free software; see the source for copying conditions. There
>+is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
>+PURPOSE
>+
>+=head1 SEE ALSO
>+
>+L<virsh(1)>, L<virt-install(1)>, L<virt-xml-validate(1)>, L<virt-top(1)>,
>+L<virt-df(1)>, L<http://www.libvirt.org/>
>+

virt-top, virt-df and virt-install are not that relevant here

also consider adding virt-host-validate (what if we add support for
admin interface checking there).

>+=cut
>--
>2.4.3
>
>--
>libvir-list mailing list
>libvir-list at redhat.com
>https://www.redhat.com/mailman/listinfo/libvir-list
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20151104/b41947b4/attachment-0001.sig>