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

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

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

+ +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, @, [, ], \, ^, _. +

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

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