virt-admin (1) - Linux Manuals

virt-admin: daemon administration interface

NAME

virt-admin - daemon administration interface

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:

  virt-admin [OPTION]... <command> [ARG]...

Where command is one of the commands listed below.

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 between commands. 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. 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 [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
quit this interactive terminal
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

 $ virt-admin version
 Compiled against library: libvirt 1.2.21
 Using library: libvirt 1.2.21
 Running against daemon: 1.2.20
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
Will print the current directory.
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.

For remote access see the documentation page at <http://libvirt.org/uri.html> on how to make URIs.

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.

SERVER COMMANDS

Following commands manipulate daemon's server internal configuration. The server is specified by its name.
srv-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:
 virsh destroy <domain>.

srv-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 srv-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.
srv-clients-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).
srv-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
 virt-admin srv-clients-info libvirtd
 nclients_max        : 120
 nclients            : 3
 nclients_unauth_max : 20
 nclients_unauth     : 0

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

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 srv-clients-list).
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

 # 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 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 <http://libvirt.org/logging.html>

BUGS

Report any bugs discovered to the libvirt community via the mailing list <http://libvirt.org/contact.html> or bug tracker <http://libvirt.org/bugs.html>. Alternatively report bugs to your software distributor / vendor.

AUTHORS

  Please refer to the AUTHORS file distributed with libvirt.

  Based on the virsh man page.

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