VIRT-ADMIN(1) Virtualization Support VIRT-ADMIN(1)
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 modify-
ing the libvirt daemon configuration at runtime, changing daemon behav-
iour 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. Any command starting
with # is treated as a comment and silently ignored, all other unrecog-
nized 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 COM-
MAND_STRING which is a single shell argument consisting of multiple
COMMAND actions and their arguments joined with whitespace and sepa-
rated by semicolons or newlines between commands, where unquoted back-
slash-newline pairs are elided. Within COMMAND_STRING, virt-admin un-
derstands 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. See NOTES.
-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 environ-
ment 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 li-
brary virt-admin is coming from
-V, --version=long
Ignore all other arguments, and prints the version of the libvirt li-
brary virt-admin is coming from.
NOTES
The virt-admin supports both the monolithic libvirtd daemon and the
modular daemons whichever is in use by your system. The connection URI
used with -c/--connect or the connect command is based on the name of
the controlled daemon e.g.: virtqemud:///system, libvirtd:///system.
Running virt-admin requires root privileges when communicating with the
system instance of a daemon (URI ending in /system) due to the communi-
cations channels used to talk to the daemon.
GENERIC COMMANDS
The following commands are generic.
help
Syntax:
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:
quit
exit
quit this interactive terminal
version
Syntax:
version
will print out the version info about which libvirt library was this
client built from. As opposed to virsh client, the output already in-
cludes 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
Syntax:
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:
pwd
Will print the current directory.
connect
Syntax:
connect [URI]
(Re)-Connect to a daemon's administrating server. The URI parameter
specifies how to connect to the administrating server. If LIBVIRT_AD-
MIN_DEFAULT_URI or uri_default (see below) were set, connect is auto-
matically issued every time a command that requires an active connec-
tion is executed. Note that this only applies if there is no connection
at all or there is an inactive one.
See NOTES on picking the correct URI corresponding to a libvirt daemon.
To find the currently used URI, check the uri command documented below.
uri
Syntax:
uri
Prints the administrating server canonical URI, can be useful in shell
mode. If no uri was specified, neither LIBVIRT_ADMIN_DEFAULT_URI envi-
ronment 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:
server-list
Lists all manageable servers contained within the daemon the client is
currently connected to.
daemon-log-filters
Syntax:
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 delim-
ited 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:
$ 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 direc-
tory containing several modules this would become "4:util"):
daemon-log-outouts
Syntax:
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 delim-
ited 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:
$ 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>"
daemon-timeout
Syntax:
daemon-timeout --timeout NUM
Sets the daemon timeout to the value of '--timeout' argument. Use
--timeout 0 to disable auto-shutdown of the daemon.
SERVER COMMANDS
The following commands manipulate daemon's server internal configura-
tion. The server is specified by its name.
server-threadpool-info
Syntax:
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 thread-
pool, 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>.
server-threadpool-set
Syntax:
server-threadpool-set server [--min-workers count] [--max-workers count] [--priority-workers count]
Change threadpool attributes on a server. Only a fraction of all at-
tributes 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, other-
wise the command results in an error.
• --priority-workers
The current number of active priority workers in a threadpool.
server-clients-info
Syntax:
server-clients-info server
Get information about the current setting of limits regarding connec-
tions 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 server-clients-info libvirtd
nclients_max : 120
nclients : 3
nclients_unauth_max : 20
nclients_unauth : 0
server-clients-set
Syntax:
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 con-
nected 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.
server-update-tls
Syntax:
server-update-tls server
Update tls context on server.
• server
Available servers on a daemon. Currently only supports 'libvirtd' or
'virtproxyd'.
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:
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:
client-info server client
Retrieve identity information about client from server. The attributes
returned may vary depending on the connection transport used. Trans-
port-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 au-
thentication 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
Syntax:
client-disconnect server client
Close a connection originating from client. The server argument speci-
fies 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 over-
rides the default URI set in any client config file.
• VIRT_ADMIN_HISTSIZE
The number of commands to remember in the command history. The de-
fault 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
AUTHORS
Please refer to the AUTHORS file distributed with libvirt.
BUGS
Please report all bugs you discover. This should be done via either:
1. the mailing list
https://libvirt.org/contact.html
2. the bug tracker
https://libvirt.org/bugs.html
Alternatively, you may report bugs to your software distributor / ven-
dor.
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 war-
ranty; 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/
VIRT-ADMIN(1)
Generated by dwww version 1.15 on Mon Jun 24 20:42:16 CEST 2024.