mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 17:34:18 +03:00
docs: convert virt-admin man page from pod to rst
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é
parent
9aca11ac6a
commit
10251eae0e
@ -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)
|
||||
|
||||
@ -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
|
||||
|
||||
636
docs/manpages/virt-admin.rst
Normal file
636
docs/manpages/virt-admin.rst
Normal 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/>`_
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
Loading…
Reference in New Issue
Block a user