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 -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list