[libvirt] [PATCH 14/17] docs: convert virt-admin man page from pod to rst
Daniel P. Berrangé
berrange at redhat.com
Fri Dec 6 14:50:39 UTC 2019
This was a semi-automated conversion. First it was run through pod2rst,
and then it was manually editted to use a rst structure that matches
expectations of rst2man.
Signed-off-by: Daniel P. Berrangé <berrange at redhat.com>
---
docs/Makefile.am | 1 +
docs/manpages/index.rst | 1 +
docs/manpages/virt-admin.rst | 610 +++++++++++++++++++++++++++++++++++
tools/Makefile.am | 5 +-
tools/virt-admin.pod | 497 ----------------------------
5 files changed, 613 insertions(+), 501 deletions(-)
create mode 100644 docs/manpages/virt-admin.rst
delete mode 100644 tools/virt-admin.pod
diff --git a/docs/Makefile.am b/docs/Makefile.am
index d63cfa50dc..1f42afedb6 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -203,6 +203,7 @@ manpages_rst = \
manpages1_rst = \
manpages/virt-pki-validate.rst \
manpages/virt-xml-validate.rst \
+ manpages/virt-admin.rst \
$(NULL)
manpages7_rst = \
$(NULL)
diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst
index 891bf17faf..d7e4bcf1d1 100644
--- a/docs/manpages/index.rst
+++ b/docs/manpages/index.rst
@@ -17,3 +17,4 @@ Tools
* `virt-xml-validate(1) <virt-xml-validate.html>`__ - validate libvirt XML files against a schema
* `virt-sanlock-cleanup(8) <virt-sanlock-cleanup.html>`__ - remove stale sanlock resource lease files
* `virt-login-shell(1) <virt-login-shell.html>`__ - tool to execute a shell within a container
+* `virt-admin(1) <virt-admin.html>`__ - daemon administration interface
diff --git a/docs/manpages/virt-admin.rst b/docs/manpages/virt-admin.rst
new file mode 100644
index 0000000000..8d28642fe3
--- /dev/null
+++ b/docs/manpages/virt-admin.rst
@@ -0,0 +1,610 @@
+==========
+virt-admin
+==========
+
+-------------------------------
+daemon administration interface
+-------------------------------
+
+:Manual section: 1
+:Manual group: Virtualization Support
+
+.. contents::
+
+SYNOPSIS
+========
+
+``virt-admin`` [*OPTION*]... [*COMMAND_STRING*]
+
+``virt-admin`` [*OPTION*]... *COMMAND* [*ARG*]...
+
+
+DESCRIPTION
+===========
+
+The ``virt-admin`` program is the main administration interface for modifying
+the libvirt daemon configuration at runtime, changing daemon behaviour as well
+as for monitoring and managing all clients connected to the daemon.
+
+The basic structure of most virt-admin usage is:
+
+.. code-block:: shell
+
+ virt-admin [OPTION]... <command> [ARG]...
+
+Where *command* is one of the commands listed below. Any *command*
+starting with ``#`` is treated as a comment and silently ignored, all
+other unrecognized *commands* are diagnosed.
+
+The ``virt-admin`` program can be used either to run one *COMMAND* by giving the
+command and its arguments on the shell command line, or a *COMMAND_STRING*
+which is a single shell argument consisting of multiple *COMMAND* actions
+and their arguments joined with whitespace and separated by semicolons or
+newlines between commands, where unquoted backslash-newline pairs are
+elided. Within *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,
+and any word starting with unquoted *#* begins a comment that ends at newline.
+If no command is given in the command line, ``virt-admin`` will then start a minimal
+interpreter waiting for your commands, and the ``quit`` command will then exit
+the program.
+
+The ``virt-admin`` program understands the following *OPTIONS*.
+
+
+``-c``, ``--connect`` *URI*
+
+Connect to the specified *URI*, as if by the ``connect`` command,
+instead of the default connection.
+
+``-d``, ``--debug`` *LEVEL*
+
+Enable debug messages at integer *LEVEL* and above. *LEVEL* can
+range from 0 to 4 (default). See the documentation of ``VIRT_ADMIN_DEBUG``
+environment variable below for the description of each *LEVEL*.
+
+``-h``, ``--help``
+
+Ignore all other arguments, and behave as if the ``help`` command were
+given instead.
+
+``-l``, ``--log`` *FILE*
+
+Output logging details to *FILE*.
+
+``-q``, ``--quiet``
+
+Avoid extra informational messages.
+
+``-v``, ``--version[=short]``
+
+Ignore all other arguments, and prints the version of the libvirt library
+virt-admin is coming from
+
+``-V``, ``--version=long``
+
+Ignore all other arguments, and prints the version of the libvirt library
+virt-admin is coming from.
+
+
+NOTES
+=====
+
+Running ``virt-admin`` requires root privileges due to the
+communications channels used to talk to the daemon. Consider changing the
+*unix_sock_group* ownership setting to grant access to specific set of users
+or modifying *unix_sock_rw_perms* permissions. Daemon configuration file
+provides more information about setting permissions.
+
+
+GENERIC COMMANDS
+================
+
+The following commands are generic.
+
+help
+----
+
+.. code-block:: shell
+
+ help [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.
+
+
+quit, exit
+----------
+
+.. code-block:: shell
+
+ quit
+ exit
+
+quit this interactive terminal
+
+version
+-------
+
+.. code-block:: shell
+
+ version
+
+will print out the version info about which libvirt library was this client
+built from. As opposed to *virsh* client, the output already includes
+the version of the daemon.
+
+Example
+~~~~~~~
+
+.. code-block:: shell
+
+ $ virt-admin version
+ Compiled against library: libvirt 1.2.21
+ Using library: libvirt 1.2.21
+ Running against daemon: 1.2.20
+
+
+
+cd
+--
+
+.. code-block:: shell
+
+ cd [directory]
+
+Will change current directory to *directory*. The default directory
+for the ``cd`` command is the home directory or, if there is no *HOME*
+variable in the environment, the root directory.
+
+This command is only available in interactive mode.
+
+pwd
+---
+
+.. code-block:: shell
+
+ pwd
+
+Will print the current directory.
+
+
+connect
+-------
+
+.. code-block:: shell
+
+ connect [URI]
+
+(Re)-Connect to a daemon's administrating server. The *URI* parameter
+specifies how to connect to the administrating server.
+If *LIBVIRT_ADMIN_DEFAULT_URI* or *uri_default* (see below) were set,
+*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 *uri* command documented below.
+
+
+uri
+---
+
+.. code-block:: shell
+
+ uri
+
+Prints the administrating server canonical URI, can be useful in shell mode. If
+no *uri* was specified, neither *LIBVIRT_ADMIN_DEFAULT_URI* environment
+variable nor *uri_default* option (libvirt-admin.conf) were set,
+libvirtd:///system is used.
+
+
+
+
+DAEMON COMMANDS
+===============
+
+
+The following commands allow one to monitor the daemon's state as well as
+directly change its internal configuration.
+
+server-list
+-----------
+
+.. code-block:: shell
+
+ server-list
+
+Lists all manageable servers contained within the daemon the client is
+currently connected to.
+
+
+daemon-log-filters
+------------------
+
+.. code-block:: shell
+
+ daemon-log-filters [--filters string]
+
+When run without arguments, this returns the currently defined set of logging
+filters. Providing an argument will cause the command to define a new set of
+logging filters.
+
+
+- *--filters*
+
+Define a new set of logging filters where multiple filters are delimited by
+space. Each filter must conform to the form described in detail by
+*/etc/libvirt/libvirtd.conf* (section 'Logging filters').
+
+
+
+Example
+~~~~~~~
+
+To define a filter which suppresses all e.g. 'virObjectUnref' DEBUG
+messages, use the following:
+
+.. code-block:: shell
+
+ $ virt-admin daemon-log-filters "4:util.object"
+
+(Note the '.' symbol which can be used to more fine-grained filters tailored
+to specific modules, in contrast, to affect the whole directory containing
+several modules this would become "4:util"):
+
+daemon-log-outouts
+------------------
+
+.. code-block:: shell
+
+ daemon-log-outputs [--outputs string]
+
+When run without arguments, this returns the currently defined set of logging
+outputs. Providing an argument will cause the command to define a new set of
+logging outputs.
+
+
+- *--outputs*
+
+Define a new set of logging outputs where multiple outputs are delimited by
+space. Each output must conform to the form described in detail by
+*/etc/libvirt/libvirtd.conf* (section 'Logging outputs').
+
+
+Example
+~~~~~~~
+
+To replace the current setting for logging outputs with one that writes to
+a file while logging errors only, the following could be used:
+
+.. code-block:: shell
+
+ $ virt-admin daemon-log-outputs "4:file:<absolute_path_to_the_file>"
+
+To define multiple outputs at once they need to be delimited by spaces:
+
+.. code-block:: shell
+
+ $ virt-admin daemon-log-outputs "4:stderr 2:syslog:<msg_ident>"
+
+
+SERVER COMMANDS
+===============
+
+The following commands manipulate daemon's server internal configuration.
+The *server* is specified by its name.
+
+server-threadpool-info
+----------------------
+
+.. code-block:: shell
+
+ server-threadpool-info server
+
+Retrieve server's threadpool attributes. These attributes include:
+
+
+- *minWorkers* as the bottom limit to the number of active workers,
+
+- *maxWorkers* as the top limit to the number of active workers,
+
+- *nWorkers* as the current number of workers in the threadpool,
+
+- *freeWorkers* as the current number of workers available for a task,
+
+- *prioWorkers* as the current number of priority workers in the threadpool, and
+
+- *jobQueueDepth* as the current depth of threadpool's job queue.
+
+
+
+Background
+~~~~~~~~~~
+
+Each daemon server utilizes a threadpool to accomplish tasks requested by
+clients connected to it. Every time a client request arrives to the server,
+it checks whether there is a worker available to accomplish the given task or
+it should create a new worker for the job (rather than being destroyed, the
+worker becomes free once the task is finished). Creating new workers, however,
+is only possible when the current number of workers is still below the
+configured upper limit.
+In addition to these 'standard' workers, a threadpool also contains a special
+set of workers called *priority* workers. Their purpose is to perform tasks
+that, unlike tasks carried out by normal workers, are within libvirt's full
+control and libvirt guarantees that such a task cannot hang, thus will always
+finish. An example of such a task this would be destroying a domain:
+
+.. code-block:: shell
+
+ $ virsh destroy <domain>.
+
+
+server-threadpool-set
+---------------------
+
+.. code-block:: shell
+
+ server-threadpool-set server [--min-workers count] [--max-workers count] [--priority-workers count]
+
+Change threadpool attributes on a server. Only a fraction of all attributes as
+described in *server-threadpool-info* is supported for the setter.
+
+
+- *--min-workers*
+
+ The bottom limit to number of active workers in a threadpool.
+
+- *--max-workers*
+
+ The upper limit to number of active workers in a threadpool. If used in
+ combination with option *--min-workers*, the value for the upper limit has to
+ be greater than the value for the bottom limit, otherwise the command results
+ in an error.
+
+- *--priority-workers*
+
+ The current number of active priority workers in a threadpool.
+
+
+server-clients-info
+-------------------
+
+.. code-block:: shell
+
+ server-clients-info server
+
+Get information about the current setting of limits regarding connections of new
+clients. This information comprises of the limits to the maximum number of
+clients connected to *server*, maximum number of clients waiting for
+authentication, in order to be connected to the server, as well as the current
+runtime values, more specifically, the current number of clients connected to
+*server* and the current number of clients waiting for authentication.
+
+Example
+~~~~~~~
+
+.. code-block:: shell
+
+ # virt-admin server-clients-info libvirtd
+ nclients_max : 120
+ nclients : 3
+ nclients_unauth_max : 20
+ nclients_unauth : 0
+
+
+server-clients-set
+------------------
+
+.. code-block:: shell
+
+ server-clients-set server [--max-clients count] [--max-unauth-clients count]
+
+Set new client-related limits on *server*.
+
+
+- *--max-clients*
+
+ Change the upper limit of the maximum overall number of clients connected to
+ *server* to value ``count``. The value for this limit has to be always greater
+ than the value of *--max-unauth-clients*.
+
+- *--max-unauth-clients*
+
+ Change the upper limit of the maximum number of clients waiting for
+ authentication, in order to be connected to *server*, to value ``count``.
+ The value for this limit has to be always lower than the value of
+ *--max-clients*.
+
+
+CLIENT COMMANDS
+===============
+
+
+The following commands provide management and monitoring of clients connected to
+one of daemon's available servers. Clients are specified by their numeric ID
+which is obtained by listing all clients connected to a specified server
+(see command ``client-list``).
+
+
+client-list
+-----------
+
+.. code-block:: shell
+
+ client-list server
+
+Print a table showing the list of clients connected to <server>, also providing
+information about transport type used on client's connection (supported
+transports include ``unix``, ``tcp``, and ``tls``), as well as providing
+information about client's connection time (system local time is used).
+
+client-info
+-----------
+
+.. code-block:: shell
+
+ client-info server client
+
+Retrieve identity information about *client* from *server*. The attributes
+returned may vary depending on the connection transport used.
+Transport-dependent attributes include local client process's pid, uid,
+user name, and group name, as well as socket address of the remote peer, see
+``Examples`` below.
+
+On the other hand, transport-independent attributes include client's SELinux
+context (if enabled on the host) and SASL username (if SASL authentication is
+enabled within daemon).
+
+Examples
+~~~~~~~~
+
+.. code-block:: shell
+
+ # virt-admin client-info libvirtd 1
+ id : 1
+ connection_time: 2016-05-03 13:27:04+0200
+ transport : unix
+ readonly : yes
+ unix_user_id : 0
+ unix_user_name : root
+ unix_group_id : 0
+ unix_group_name: root
+ unix_process_id: 10201
+
+ # virt-admin client-info libvirtd 2
+ id : 2
+ connection_time: 2016-05-03 13:30:33+0200
+ transport : tcp
+ readonly : no
+ sock_addr : 127.0.0.1:57060
+
+
+client-disconnect
+-----------------
+
+.. code-block:: shell
+
+ client-disconnect server client
+
+Close a connection originating from *client*. The *server* argument
+specifies the name of the server *client* is currently connected to.
+
+
+ENVIRONMENT
+===========
+
+The following environment variables can be set to alter the behaviour
+of ``virt-admin``
+
+- VIRT_ADMIN_DEBUG=<0 to 4>
+
+ Turn on verbose debugging of virt-admin commands. Valid levels are
+
+ * VIRT_ADMIN_DEBUG=0
+
+ DEBUG - Messages at ALL levels get logged
+
+ * VIRT_ADMIN_DEBUG=1
+
+ INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
+
+ * VIRT_ADMIN_DEBUG=2
+
+ NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
+
+ * VIRT_ADMIN_DEBUG=3
+
+ WARNING - Logs messages at levels WARNING and ERROR
+
+ * VIRT_ADMIN_DEBUG=4
+
+ ERROR - Messages at only ERROR level gets logged.
+
+
+- VIRT_ADMIN_LOG_FILE=``LOGFILE``
+
+ The file to log virt-admin debug messages.
+
+- 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 ``connect`` option. This overrides the
+ default URI set in any client config file.
+
+- VIRT_ADMIN_HISTSIZE
+
+ The number of commands to remember in the command history. The
+ default value is 500.
+
+- LIBVIRT_DEBUG=LEVEL
+
+ Turn on verbose debugging of all libvirt API calls. Valid levels are
+
+ * LIBVIRT_DEBUG=1
+
+ Messages at level DEBUG or above
+
+ * LIBVIRT_DEBUG=2
+
+ Messages at level INFO or above
+
+ * LIBVIRT_DEBUG=3
+
+ Messages at level WARNING or above
+
+ * LIBVIRT_DEBUG=4
+
+ Messages at level ERROR or above
+
+For further information about debugging options consult
+`https://libvirt.org/logging.html <https://libvirt.org/logging.html>`_
+
+
+AUTHORS
+=======
+
+Please refer to the AUTHORS file distributed with libvirt.
+
+
+BUGS
+====
+
+Please report all bugs you discover. This should be done via either:
+
+#. the mailing list
+
+ `https://libvirt.org/contact.html <https://libvirt.org/contact.html>`_
+
+#. the bug tracker
+
+ `https://libvirt.org/bugs.html <https://libvirt.org/bugs.html>`_
+
+Alternatively, you may report bugs to your software distributor / vendor.
+
+
+COPYRIGHT
+=========
+
+Copyright (C) 2015 Red Hat, Inc., and the authors listed in the
+libvirt AUTHORS file.
+
+
+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
+
+
+SEE ALSO
+========
+
+virsh(1), virt-xml-validate(1), virt-host-validate(1),
+`https://libvirt.org/ <https://libvirt.org/>`_
diff --git a/tools/Makefile.am b/tools/Makefile.am
index 4480a94539..f490a61348 100644
--- a/tools/Makefile.am
+++ b/tools/Makefile.am
@@ -53,12 +53,10 @@ ICON_FILES = \
virsh_win_icon.rc
PODFILES = \
- virt-admin.pod \
virsh.pod \
$(NULL)
MANINFILES = \
- virt-admin.1.in \
virsh.1.in \
$(NULL)
@@ -88,8 +86,7 @@ bin_SCRIPTS = virt-xml-validate virt-pki-validate
bin_PROGRAMS = virsh virt-admin
libexec_SCRIPTS = libvirt-guests.sh
man1_MANS = \
- virsh.1 \
- virt-admin.1
+ virsh.1
if WITH_SANLOCK
sbin_SCRIPTS = virt-sanlock-cleanup
diff --git a/tools/virt-admin.pod b/tools/virt-admin.pod
deleted file mode 100644
index 1ea6defa0e..0000000000
--- a/tools/virt-admin.pod
+++ /dev/null
@@ -1,497 +0,0 @@
-=head1 NAME
-
-virt-admin - daemon administration 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 administration interface for modifying
-the libvirt daemon configuration at runtime, changing daemon behaviour as well
-as for monitoring and managing all clients 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. Any I<command>
-starting with B<#> is treated as a comment and silently ignored, all
-other unrecognized I<command>s are diagnosed.
-
-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 or
-newlines between commands, where unquoted backslash-newline pairs are
-elided. 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,
-and any word starting with unquoted I<#> begins a comment that ends at newline.
-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<VIRT_ADMIN_DEBUG>
-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.
-
-=item B<-l>, B<--log> I<FILE>
-
-Output logging details to I<FILE>.
-
-=item B<-q>, B<--quiet>
-
-Avoid extra informational messages.
-
-=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
-
-Running B<virt-admin> requires root privileges due to the
-communications channels used to talk to the daemon. Consider changing the
-I<unix_sock_group> ownership setting to grant access to specific set of users
-or modifying I<unix_sock_rw_perms> permissions. Daemon configuration file
-provides more information about setting permissions.
-
-=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 version info about which libvirt library was this client
-built from. As opposed to I<virsh> client, the output already includes
-the version of the 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>]
-
-(Re)-Connect to a daemon's administrating server. The I<URI> parameter
-specifies how to connect to the administrating server.
-If I<LIBVIRT_ADMIN_DEFAULT_URI> or I<uri_default> (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.
-
-=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> environment
-variable nor I<uri_default> option (libvirt-admin.conf) were set,
-libvirtd:///system is used.
-
-=back
-
-=head1 DAEMON COMMANDS
-
-The following commands allow one to monitor the daemon's state as well as
-directly change its internal configuration.
-
-=over 4
-
-=item B<server-list>
-
-Lists all manageable servers contained within the daemon the client is
-currently connected to.
-
-=item B<daemon-log-filters> [I<--filters> B<string>]
-
-When run without arguments, this returns the currently defined set of logging
-filters. Providing an argument will cause the command to define a new set of
-logging filters.
-
-=over 4
-
-=item I<--filters>
-
-Define a new set of logging filters where multiple filters are delimited by
-space. Each filter must conform to the form described in detail by
-I</etc/libvirt/libvirtd.conf> (section 'Logging filters').
-
-=back
-
-B<Example>
-
- To define a filter which suppresses all e.g. 'virObjectUnref' DEBUG
- messages, use the following:
-
- $ virt-admin daemon-log-filters "4:util.object"
-
- (Note the '.' symbol which can be used to more fine-grained filters tailored
- to specific modules, in contrast, to affect the whole directory containing
- several modules this would become "4:util"):
-
-=item B<daemon-log-outputs> [I<--outputs> B<string>]
-
-When run without arguments, this returns the currently defined set of logging
-outputs. Providing an argument will cause the command to define a new set of
-logging outputs.
-
-=over 4
-
-=item I<--outputs>
-
-Define a new set of logging outputs where multiple outputs are delimited by
-space. Each output must conform to the form described in detail by
-I</etc/libvirt/libvirtd.conf> (section 'Logging outputs').
-
-=back
-
-B<Example>
-
- To replace the current setting for logging outputs with one that writes to
- a file while logging errors only, the following could be used:
-
- $ virt-admin daemon-log-outputs "4:file:<absolute_path_to_the_file>"
-
- To define multiple outputs at once they need to be delimited by spaces:
-
- $ virt-admin daemon-log-outputs "4:stderr 2:syslog:<msg_ident>"
-
-=back
-
-=head1 SERVER COMMANDS
-
-The following commands manipulate daemon's server internal configuration.
-The I<server> is specified by its name.
-
-=over 4
-
-=item B<server-threadpool-info> I<server>
-
-Retrieve server's threadpool attributes. These attributes include:
-
-=over 4
-
-=item I<minWorkers>
-as the bottom limit to the number of active workers,
-
-=item I<maxWorkers>
-as the top limit to the number of active workers,
-
-=item I<nWorkers>
-as the current number of workers in the threadpool,
-
-=item I<freeWorkers>
-as the current number of workers available for a task,
-
-=item I<prioWorkers>
-as the current number of priority workers in the threadpool, and
-
-=item I<jobQueueDepth>
-as the current depth of threadpool's job queue.
-
-=back
-
-B<Background>
-
-Each daemon server utilizes a threadpool to accomplish tasks requested by
-clients connected to it. Every time a client request arrives to the server,
-it checks whether there is a worker available to accomplish the given task or
-it should create a new worker for the job (rather than being destroyed, the
-worker becomes free once the task is finished). Creating new workers, however,
-is only possible when the current number of workers is still below the
-configured upper limit.
-
-In addition to these 'standard' workers, a threadpool also contains a special
-set of workers called I<priority> workers. Their purpose is to perform tasks
-that, unlike tasks carried out by normal workers, are within libvirt's full
-control and libvirt guarantees that such a task cannot hang, thus will always
-finish. An example of such a task this would be destroying a domain:
- $ virsh destroy <domain>.
-
-=item B<server-threadpool-set> I<server> [I<--min-workers> B<count>]
-[I<--max-workers> B<count>] [I<--priority-workers> B<count>]
-
-Change threadpool attributes on a server. Only a fraction of all attributes as
-described in I<server-threadpool-info> is supported for the setter.
-
-=over 4
-
-=item I<--min-workers>
-
-The bottom limit to number of active workers in a threadpool.
-
-=item I<--max-workers>
-
-The upper limit to number of active workers in a threadpool. If used in
-combination with option I<--min-workers>, the value for the upper limit has to
-be greater than the value for the bottom limit, otherwise the command results
-in an error.
-
-=item I<--priority-workers>
-
-The current number of active priority workers in a threadpool.
-
-=back
-
-=item B<server-clients-info> I<server>
-
-Get information about the current setting of limits regarding connections of new
-clients. This information comprises of the limits to the maximum number of
-clients connected to I<server>, maximum number of clients waiting for
-authentication, in order to be connected to the server, as well as the current
-runtime values, more specifically, the current number of clients connected to
-I<server> and the current number of clients waiting for authentication.
-
-B<Example>
- # virt-admin server-clients-info libvirtd
- nclients_max : 120
- nclients : 3
- nclients_unauth_max : 20
- nclients_unauth : 0
-
-=item B<server-clients-set> I<server> [I<--max-clients> B<count>]
-[I<--max-unauth-clients> B<count>]
-
-Set new client-related limits on I<server>.
-
-=over 4
-
-=item I<--max-clients>
-
-Change the upper limit of the maximum overall number of clients connected to
-I<server> to value B<count>. The value for this limit has to be always greater
-than the value of I<--max-unauth-clients>.
-
-=item I<--max-unauth-clients>
-
-Change the upper limit of the maximum number of clients waiting for
-authentication, in order to be connected to I<server>, to value B<count>.
-The value for this limit has to be always lower than the value of
-I<--max-clients>.
-
-=back
-
-=back
-
-=head1 CLIENT COMMANDS
-
-The following commands provide management and monitoring of clients connected to
-one of daemon's available servers. Clients are specified by their numeric ID
-which is obtained by listing all clients connected to a specified server
-(see command B<client-list>).
-
-=over 4
-
-=item B<client-list> I<server>
-
-Print a table showing the list of clients connected to <server>, also providing
-information about transport type used on client's connection (supported
-transports include B<unix>, B<tcp>, and B<tls>), as well as providing
-information about client's connection time (system local time is used).
-
-=item B<client-info> I<server> I<client>
-
-Retrieve identity information about I<client> from I<server>. The attributes
-returned may vary depending on the connection transport used.
-Transport-dependent attributes include local client process's pid, uid,
-user name, and group name, as well as socket address of the remote peer, see
-B<Examples> below.
-
-On the other hand, transport-independent attributes include client's SELinux
-context (if enabled on the host) and SASL username (if SASL authentication is
-enabled within daemon).
-
-B<Examples>
-
- # virt-admin client-info libvirtd 1
- id : 1
- connection_time: 2016-05-03 13:27:04+0200
- transport : unix
- readonly : yes
- unix_user_id : 0
- unix_user_name : root
- unix_group_id : 0
- unix_group_name: root
- unix_process_id: 10201
-
- # virt-admin client-info libvirtd 2
- id : 2
- connection_time: 2016-05-03 13:30:33+0200
- transport : tcp
- readonly : no
- sock_addr : 127.0.0.1:57060
-
-=item B<client-disconnect> I<server> I<client>
-
-Close a connection originating from I<client>. The I<server> argument
-specifies the name of the server I<client> is currently connected to.
-
-=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 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
-L<https://libvirt.org/logging.html>
-
-=back
-
-=head1 BUGS
-
-Report any bugs discovered to the libvirt community via the mailing
-list L<https://libvirt.org/contact.html> or bug tracker
-L<https://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 virsh man page.
-
-=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-xml-validate(1)>, L<virt-host-validate(1)>,
-L<https://libvirt.org/>
-
-=cut
--
2.23.0
More information about the libvir-list
mailing list