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

Wed Oct 14 11:25:14 UTC 2015

On 13.10.2015 15:38, Erik Skultety wrote:
> ---
>  tools/Makefile.am    |   8 +-
>  tools/virt-admin.pod | 297 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 304 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
> +
>  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..348353d
> --- /dev/null
> +++ b/tools/virt-admin.pod
> @@ -0,0 +1,297 @@
> +=head1 NAME
> +
> +virt-admin - virtualization daemon administrating user interface
> +
> +=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
> +the libvirt daemon configuration as well as to monitor and manage all clients
> +connected to the daemon.
> +
> +The basic structure of most virt-admin usage is:
> +
> +  virt-admin [OPTION]... <command> <domain> [ARG]...

s/domain// here and everywhere.

> +
> +Where I<command> is one of the commands listed below; I<domain> is the
> +numeric domain id, or the domain name, or the domain UUID; and I<ARGS>
> +are command specific options.  There are a few exceptions to this rule
> +in the cases where the command in question acts on all domains, the
> +entire machine, or directly on the xen hypervisor.  Those exceptions
> +will be clear for each of those commands.  Note: it is permissible to
> +give numeric names to domains, however, doing so will result in a
> +domain that can only be identified by domain id. In other words, if a
> +numeric value is supplied it will be interpreted as a domain id, not
> +as a name.

This paragraph ^^ except for the first sentence can be dropped. We are
not going to support domains here ..

> +
> +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>
> +environment variable below for the description of each I<LEVEL>.
> +
> +=item B<-e>, B<--escape> I<string>
> +
> +Set alternative escape sequence for I<console> command. By default,
> +telnet's B<^]> is used. Allowed characters when using hat notation are:
> +alphabetic character, @, [, ], \, ^, _.
> +

Not really. I went back to 2/9 and you've dropped --escape there
(correctly). You need to drop it here too.

> +=item B<-h>, B<--help>
> +
> +Ignore all other arguments, and behave as if the B<help> command were
> +given instead.
> +
> +=item B<-l>, B<--log> I<FILE>
> +
> +Output logging details to I<FILE>.
> +
> +=item B<-q>, B<--quiet>
> +
> +Avoid extra informational messages.
> +
> +=item B<-r>, B<--readonly>
> +
> +Make the initial connection read-only, as if by the I<--readonly>
> +option of the B<connect> command.
> +

Again, we don't support --readonly.

> +=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 and which options and driver are compiled in.
> +
> +=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.
> +
> +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>.
> +
> +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.
> +
> +=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 what this built from. As opposed
> +to I<virsh> client, the output already includes the version of the libvirt daemon.
> +
> +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>] [I<--readonly>]
> +
> +(Re)-Connect to a daemon's administrating server. When the shell is first started, this
> +is automatically run with the I<URI> parameter requested by the C<-c>
> +option on the command line. The I<URI> parameter specifies how to
> +connect to the hypervisor. The documentation page at
> +L<http://libvirt.org/uri.html> list the values supported, but the most
> +common are:
> +
> +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.
> +The I<--readonly> option allows for read-only connection
> +
> +=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.
> +
> +=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>
> +
> +=head1 COPYRIGHT
> +
> +Copyright (C) 2005, 2007-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/>
> +
> +=cut
> 

You don't describe connect command. Otherwise looking good.

Michal