shaba/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-23 21:34:54 +03:00
Code Releases Activity

docs: convert virt-admin man page from pod to rst

Browse Source 
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.

Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This commit is contained in:
Daniel P. Berrangé 2019-10-18 15:29:47 +01:00
parent 9aca11ac6a
commit 10251eae0e
5 changed files with 639 additions and 501 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/Makefile.am
View File

@ -203,6 +203,7 @@ manpages_rst = \
manpages1_rst = \ manpages1_rst = \
manpages/virt-pki-validate.rst \ manpages/virt-pki-validate.rst \
manpages/virt-xml-validate.rst \ manpages/virt-xml-validate.rst \
manpages/virt-admin.rst \
$(NULL) $(NULL)
manpages7_rst = \ manpages7_rst = \
$(NULL) $(NULL)

1
docs/manpages/index.rst
View File

@ -17,3 +17,4 @@ Tools
* `virt-xml-validate(1) <virt-xml-validate.html>`__ - validate libvirt XML files against a schema * `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-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-login-shell(1) <virt-login-shell.html>`__ - tool to execute a shell within a container
* `virt-admin(1) <virt-admin.html>`__ - daemon administration interface

636
docs/manpages/virt-admin.rst Normal file
View File

@ -0,0 +1,636 @@
==========
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
----
**Syntax:**
.. 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
----------
**Syntax:**
.. code-block:: shell
quit
exit
quit this interactive terminal
version
-------
**Syntax:**
.. 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
--
**Syntax:**
.. 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
---
**Syntax:**
.. code-block:: shell
pwd
Will print the current directory.
connect
-------
**Syntax:**
.. 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
---
**Syntax:**
.. 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
-----------
**Syntax:**
.. code-block:: shell
server-list
Lists all manageable servers contained within the daemon the client is
currently connected to.
daemon-log-filters
------------------
**Syntax:**
.. 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
------------------
**Syntax:**
.. 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
----------------------
**Syntax:**
.. 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
---------------------
**Syntax:**
.. 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
-------------------
**Syntax:**
.. 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
------------------
**Syntax:**
.. 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
-----------
**Syntax:**
.. 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
-----------
**Syntax:**
.. 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
-----------------
**Syntax:**
.. 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/>`_

5
tools/Makefile.am
View File

@ -53,12 +53,10 @@ ICON_FILES = \
virsh_win_icon.rc virsh_win_icon.rc
PODFILES = \ PODFILES = \
virt-admin.pod \
virsh.pod \ virsh.pod \
$(NULL) $(NULL)
MANINFILES = \ MANINFILES = \
virt-admin.1.in \
virsh.1.in \ virsh.1.in \
$(NULL) $(NULL)
@ -88,8 +86,7 @@ bin_SCRIPTS = virt-xml-validate virt-pki-validate
bin_PROGRAMS = virsh virt-admin bin_PROGRAMS = virsh virt-admin
libexec_SCRIPTS = libvirt-guests.sh libexec_SCRIPTS = libvirt-guests.sh
man1_MANS = \ man1_MANS = \
virsh.1 \ virsh.1
virt-admin.1
if WITH_SANLOCK if WITH_SANLOCK
sbin_SCRIPTS = virt-sanlock-cleanup sbin_SCRIPTS = virt-sanlock-cleanup

497
tools/virt-admin.pod
View File

@ -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