1VIRT-ADMIN(1) Virtualization Support VIRT-ADMIN(1)
2
6 virt-admin - daemon administration interface
7
9 virt-admin [OPTION]... [COMMAND_STRING]
10 virt-admin [OPTION]... COMMAND [ARG]...
12
14 The virt-admin program is the main administration interface for modify‐
15 ing the libvirt daemon configuration at runtime, changing daemon behav‐
16 iour as well as for monitoring and managing all clients connected to
17 the daemon.
18 The basic structure of most virt-admin usage is:
20 virt-admin [OPTION]... <command> [ARG]...
22 Where command is one of the commands listed below. Any command starting
24 with # is treated as a comment and silently ignored, all other unrecog‐
25 nized commands are diagnosed.
26 The virt-admin program can be used either to run one COMMAND by giving
28 the command and its arguments on the shell command line, or a COM‐
29 MAND_STRING which is a single shell argument consisting of multiple
30 COMMAND actions and their arguments joined with whitespace and sepa‐
31 rated by semicolons or newlines between commands, where unquoted back‐
32 slash-newline pairs are elided. Within COMMAND_STRING, virt-admin
33 understands the same single, double, and backslash escapes as the
34 shell, although you must add another layer of shell escaping in creat‐
35 ing the single shell argument, and any word starting with unquoted #
36 begins a comment that ends at newline. If no command is given in the
37 command line, virt-admin will then start a minimal interpreter waiting
38 for your commands, and the quit command will then exit the program.
39 The virt-admin program understands the following OPTIONS.
41 -c, --connect URI
43 Connect to the specified URI, as if by the connect command, instead of
45 the default connection.
46 -d, --debug LEVEL
48 Enable debug messages at integer LEVEL and above. LEVEL can range from
50 0 to 4 (default). See the documentation of VIRT_ADMIN_DEBUG environ‐
51 ment variable below for the description of each LEVEL.
52 -h, --help
54 Ignore all other arguments, and behave as if the help command were
56 given instead.
57 -l, --log FILE
59 Output logging details to FILE.
61 -q, --quiet
63 Avoid extra informational messages.
65 -v, --version[=short]
67 Ignore all other arguments, and prints the version of the libvirt
69 library virt-admin is coming from
70 -V, --version=long
72 Ignore all other arguments, and prints the version of the libvirt
74 library virt-admin is coming from.
75
77 Running virt-admin requires root privileges due to the communications
78 channels used to talk to the daemon. Consider changing the
79 unix_sock_group ownership setting to grant access to specific set of
80 users or modifying unix_sock_rw_perms permissions. Daemon configuration
81 file provides more information about setting permissions.
82
84 The following commands are generic.
85 help
87 Syntax:
88 help [command-or-group]
90 This lists each of the virt-admin commands. When used without options,
92 all commands are listed, one per line, grouped into related categories,
93 displaying the keyword for each group.
94 To display detailed information for a specific command, use its name as
96 the option.
97 quit, exit
99 Syntax:
100 quit
102 exit
103 quit this interactive terminal
105 version
107 Syntax:
108 version
110 will print out the version info about which libvirt library was this
112 client built from. As opposed to virsh client, the output already
113 includes the version of the daemon.
114 Example:
116 $ virt-admin version
118 Compiled against library: libvirt 1.2.21
119 Using library: libvirt 1.2.21
120 Running against daemon: 1.2.20
121 cd
123 Syntax:
124 cd [directory]
126 Will change current directory to directory. The default directory for
128 the cd command is the home directory or, if there is no HOME variable
129 in the environment, the root directory.
130 This command is only available in interactive mode.
132 pwd
134 Syntax:
135 pwd
137 Will print the current directory.
139 connect
141 Syntax:
142 connect [URI]
144 (Re)-Connect to a daemon's administrating server. The URI parameter
146 specifies how to connect to the administrating server. If LIB‐
147 VIRT_ADMIN_DEFAULT_URI or uri_default (see below) were set, connect is
148 automatically issued every time a command that requires an active con‐
149 nection is executed. Note that this only applies if there is no connec‐
150 tion at all or there is an inactive one.
151 To find the currently used URI, check the uri command documented below.
153 uri
155 Syntax:
156 uri
158 Prints the administrating server canonical URI, can be useful in shell
160 mode. If no uri was specified, neither LIBVIRT_ADMIN_DEFAULT_URI envi‐
161 ronment variable nor uri_default option (libvirt-admin.conf) were set,
162 libvirtd:///system is used.
163
165 The following commands allow one to monitor the daemon's state as well
166 as directly change its internal configuration.
167 server-list
169 Syntax:
170 server-list
172 Lists all manageable servers contained within the daemon the client is
174 currently connected to.
175 daemon-log-filters
177 Syntax:
178 daemon-log-filters [--filters string]
180 When run without arguments, this returns the currently defined set of
182 logging filters. Providing an argument will cause the command to define
183 a new set of logging filters.
184 · --filters
186 Define a new set of logging filters where multiple filters are delim‐
188 ited by space. Each filter must conform to the form described in detail
189 by /etc/libvirt/libvirtd.conf (section 'Logging filters').
190 Example:
192 To define a filter which suppresses all e.g. 'virObjectUnref' DEBUG
194 messages, use the following:
195 $ virt-admin daemon-log-filters "4:util.object"
197 (Note the '.' symbol which can be used to more fine-grained filters
199 tailored to specific modules, in contrast, to affect the whole direc‐
200 tory containing several modules this would become "4:util"):
201 daemon-log-outouts
203 Syntax:
204 daemon-log-outputs [--outputs string]
206 When run without arguments, this returns the currently defined set of
208 logging outputs. Providing an argument will cause the command to define
209 a new set of logging outputs.
210 · --outputs
212 Define a new set of logging outputs where multiple outputs are delim‐
214 ited by space. Each output must conform to the form described in detail
215 by /etc/libvirt/libvirtd.conf (section 'Logging outputs').
216 Example:
218 To replace the current setting for logging outputs with one that writes
220 to a file while logging errors only, the following could be used:
221 $ virt-admin daemon-log-outputs "4:file:<absolute_path_to_the_file>"
223 To define multiple outputs at once they need to be delimited by spaces:
225 $ virt-admin daemon-log-outputs "4:stderr 2:syslog:<msg_ident>"
227
229 The following commands manipulate daemon's server internal configura‐
230 tion. The server is specified by its name.
231 server-threadpool-info
233 Syntax:
234 server-threadpool-info server
236 Retrieve server's threadpool attributes. These attributes include:
238 · minWorkers as the bottom limit to the number of active workers,
240 · maxWorkers as the top limit to the number of active workers,
242 · nWorkers as the current number of workers in the threadpool,
244 · freeWorkers as the current number of workers available for a task,
246 · prioWorkers as the current number of priority workers in the thread‐
248 pool, and
249 · jobQueueDepth as the current depth of threadpool's job queue.
251 Background
253 Each daemon server utilizes a threadpool to accomplish tasks requested
255 by clients connected to it. Every time a client request arrives to the
256 server, it checks whether there is a worker available to accomplish the
257 given task or it should create a new worker for the job (rather than
258 being destroyed, the worker becomes free once the task is finished).
259 Creating new workers, however, is only possible when the current number
260 of workers is still below the configured upper limit. In addition to
261 these 'standard' workers, a threadpool also contains a special set of
262 workers called priority workers. Their purpose is to perform tasks
263 that, unlike tasks carried out by normal workers, are within libvirt's
264 full control and libvirt guarantees that such a task cannot hang, thus
265 will always finish. An example of such a task this would be destroying
266 a domain:
267 $ virsh destroy <domain>.
269 server-threadpool-set
271 Syntax:
272 server-threadpool-set server [--min-workers count] [--max-workers count] [--priority-workers count]
274 Change threadpool attributes on a server. Only a fraction of all
276 attributes as described in server-threadpool-info is supported for the
277 setter.
278 · --min-workers
280 The bottom limit to number of active workers in a threadpool.
282 · --max-workers
284 The upper limit to number of active workers in a threadpool. If used
286 in combination with option --min-workers, the value for the upper
287 limit has to be greater than the value for the bottom limit, other‐
288 wise the command results in an error.
289 · --priority-workers
291 The current number of active priority workers in a threadpool.
293 server-clients-info
295 Syntax:
296 server-clients-info server
298 Get information about the current setting of limits regarding connec‐
300 tions of new clients. This information comprises of the limits to the
301 maximum number of clients connected to server, maximum number of
302 clients waiting for authentication, in order to be connected to the
303 server, as well as the current runtime values, more specifically, the
304 current number of clients connected to server and the current number of
305 clients waiting for authentication.
306 Example:
308 # virt-admin server-clients-info libvirtd
310 nclients_max : 120
311 nclients : 3
312 nclients_unauth_max : 20
313 nclients_unauth : 0
314 server-clients-set
316 Syntax:
317 server-clients-set server [--max-clients count] [--max-unauth-clients count]
319 Set new client-related limits on server.
321 · --max-clients
323 Change the upper limit of the maximum overall number of clients con‐
325 nected to server to value count. The value for this limit has to be
326 always greater than the value of --max-unauth-clients.
327 · --max-unauth-clients
329 Change the upper limit of the maximum number of clients waiting for
331 authentication, in order to be connected to server, to value count.
332 The value for this limit has to be always lower than the value of
333 --max-clients.
334
336 The following commands provide management and monitoring of clients
337 connected to one of daemon's available servers. Clients are specified
338 by their numeric ID which is obtained by listing all clients connected
339 to a specified server (see command client-list).
340 client-list
342 Syntax:
343 client-list server
345 Print a table showing the list of clients connected to <server>, also
347 providing information about transport type used on client's connection
348 (supported transports include unix, tcp, and tls), as well as providing
349 information about client's connection time (system local time is used).
350 client-info
352 Syntax:
353 client-info server client
355 Retrieve identity information about client from server. The attributes
357 returned may vary depending on the connection transport used. Trans‐
358 port-dependent attributes include local client process's pid, uid, user
359 name, and group name, as well as socket address of the remote peer, see
360 Examples below.
361 On the other hand, transport-independent attributes include client's
363 SELinux context (if enabled on the host) and SASL username (if SASL
364 authentication is enabled within daemon).
365 Examples:
367 # virt-admin client-info libvirtd 1
369 id : 1
370 connection_time: 2016-05-03 13:27:04+0200
371 transport : unix
372 readonly : yes
373 unix_user_id : 0
374 unix_user_name : root
375 unix_group_id : 0
376 unix_group_name: root
377 unix_process_id: 10201
378 # virt-admin client-info libvirtd 2
380 id : 2
381 connection_time: 2016-05-03 13:30:33+0200
382 transport : tcp
383 readonly : no
384 sock_addr : 127.0.0.1:57060
385 client-disconnect
387 Syntax:
388 client-disconnect server client
390 Close a connection originating from client. The server argument speci‐
392 fies the name of the server client is currently connected to.
393
395 The following environment variables can be set to alter the behaviour
396 of virt-admin
397 · VIRT_ADMIN_DEBUG=<0 to 4>
399 Turn on verbose debugging of virt-admin commands. Valid levels are
401 · VIRT_ADMIN_DEBUG=0
403 DEBUG - Messages at ALL levels get logged
405 · VIRT_ADMIN_DEBUG=1
407 INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
409 · VIRT_ADMIN_DEBUG=2
411 NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
413 · VIRT_ADMIN_DEBUG=3
415 WARNING - Logs messages at levels WARNING and ERROR
417 · VIRT_ADMIN_DEBUG=4
419 ERROR - Messages at only ERROR level gets logged.
421 · VIRT_ADMIN_LOG_FILE=``LOGFILE``
423 The file to log virt-admin debug messages.
425 · LIBVIRT_ADMIN_DEFAULT_URI
427 The daemon whose admin server to connect to by default. Set this to a
429 URI, in the same format as accepted by the connect option. This over‐
430 rides the default URI set in any client config file.
431 · VIRT_ADMIN_HISTSIZE
433 The number of commands to remember in the command history. The
435 default value is 500.
436 · LIBVIRT_DEBUG=LEVEL
438 Turn on verbose debugging of all libvirt API calls. Valid levels are
440 · LIBVIRT_DEBUG=1
442 Messages at level DEBUG or above
444 · LIBVIRT_DEBUG=2
446 Messages at level INFO or above
448 · LIBVIRT_DEBUG=3
450 Messages at level WARNING or above
452 · LIBVIRT_DEBUG=4
454 Messages at level ERROR or above
456 For further information about debugging options consult
458 https://libvirt.org/logging.html
459
461 Please refer to the AUTHORS file distributed with libvirt.
462
464 Please report all bugs you discover. This should be done via either:
465 1. the mailing list
467 https://libvirt.org/contact.html
469 2. the bug tracker
471 https://libvirt.org/bugs.html
473 Alternatively, you may report bugs to your software distributor / ven‐
475 dor.
476
478 Copyright (C) 2015 Red Hat, Inc., and the authors listed in the libvirt
479 AUTHORS file.
480
482 virt-admin is distributed under the terms of the GNU LGPL v2+. This is
483 free software; see the source for copying conditions. There is NO war‐
484 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
485
487 virsh(1), virt-xml-validate(1), virt-host-validate(1),
488 https://libvirt.org/
489 VIRT-ADMIN(1)