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 un‐
33 derstands the same single, double, and backslash escapes as the shell,
34 although you must add another layer of shell escaping in creating the
35 single shell argument, and any word starting with unquoted # begins a
36 comment that ends at newline. If no command is given in the command
37 line, virt-admin will then start a minimal interpreter waiting for your
38 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. See NOTES.
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 li‐
69 brary virt-admin is coming from
70 -V, --version=long
72 Ignore all other arguments, and prints the version of the libvirt li‐
74 brary virt-admin is coming from.
75
77 The virt-admin supports both the monolithic libvirtd daemon and the
78 modular daemons whichever is in use by your system. The connection URI
79 used with -c/--connect or the connect command is based on the name of
80 the controlled daemon e.g.: virtqemud:///system, libvirtd:///system.
81 Running virt-admin requires root privileges when communicating with the
83 system instance of a daemon (URI ending in /system) due to the communi‐
84 cations channels used to talk to the daemon.
85
87 The following commands are generic.
88 help
90 Syntax:
91 help [command-or-group]
93 This lists each of the virt-admin commands. When used without options,
95 all commands are listed, one per line, grouped into related categories,
96 displaying the keyword for each group.
97 To display detailed information for a specific command, use its name as
99 the option.
100 quit, exit
102 Syntax:
103 quit
105 exit
106 quit this interactive terminal
108 version
110 Syntax:
111 version
113 will print out the version info about which libvirt library was this
115 client built from. As opposed to virsh client, the output already in‐
116 cludes the version of the daemon.
117 Example:
119 $ virt-admin version
121 Compiled against library: libvirt 1.2.21
122 Using library: libvirt 1.2.21
123 Running against daemon: 1.2.20
124 cd
126 Syntax:
127 cd [directory]
129 Will change current directory to directory. The default directory for
131 the cd command is the home directory or, if there is no HOME variable
132 in the environment, the root directory.
133 This command is only available in interactive mode.
135 pwd
137 Syntax:
138 pwd
140 Will print the current directory.
142 connect
144 Syntax:
145 connect [URI]
147 (Re)-Connect to a daemon's administrating server. The URI parameter
149 specifies how to connect to the administrating server. If LIBVIRT_AD‐
150 MIN_DEFAULT_URI or uri_default (see below) were set, connect is auto‐
151 matically issued every time a command that requires an active connec‐
152 tion is executed. Note that this only applies if there is no connection
153 at all or there is an inactive one.
154 See NOTES on picking the correct URI corresponding to a libvirt daemon.
156 To find the currently used URI, check the uri command documented below.
158 uri
160 Syntax:
161 uri
163 Prints the administrating server canonical URI, can be useful in shell
165 mode. If no uri was specified, neither LIBVIRT_ADMIN_DEFAULT_URI envi‐
166 ronment variable nor uri_default option (libvirt-admin.conf) were set,
167 libvirtd:///system is used.
168
170 The following commands allow one to monitor the daemon's state as well
171 as directly change its internal configuration.
172 server-list
174 Syntax:
175 server-list
177 Lists all manageable servers contained within the daemon the client is
179 currently connected to.
180 daemon-log-filters
182 Syntax:
183 daemon-log-filters [--filters string]
185 When run without arguments, this returns the currently defined set of
187 logging filters. Providing an argument will cause the command to define
188 a new set of logging filters.
189 • --filters
191 Define a new set of logging filters where multiple filters are delim‐
193 ited by space. Each filter must conform to the form described in detail
194 by /etc/libvirt/libvirtd.conf (section 'Logging filters').
195 Example:
197 To define a filter which suppresses all e.g. 'virObjectUnref' DEBUG
199 messages, use the following:
200 $ virt-admin daemon-log-filters "4:util.object"
202 (Note the '.' symbol which can be used to more fine-grained filters
204 tailored to specific modules, in contrast, to affect the whole direc‐
205 tory containing several modules this would become "4:util"):
206 daemon-log-outouts
208 Syntax:
209 daemon-log-outputs [--outputs string]
211 When run without arguments, this returns the currently defined set of
213 logging outputs. Providing an argument will cause the command to define
214 a new set of logging outputs.
215 • --outputs
217 Define a new set of logging outputs where multiple outputs are delim‐
219 ited by space. Each output must conform to the form described in detail
220 by /etc/libvirt/libvirtd.conf (section 'Logging outputs').
221 Example:
223 To replace the current setting for logging outputs with one that writes
225 to a file while logging errors only, the following could be used:
226 $ virt-admin daemon-log-outputs "4:file:<absolute_path_to_the_file>"
228 To define multiple outputs at once they need to be delimited by spaces:
230 $ virt-admin daemon-log-outputs "4:stderr 2:syslog:<msg_ident>"
232
234 The following commands manipulate daemon's server internal configura‐
235 tion. The server is specified by its name.
236 server-threadpool-info
238 Syntax:
239 server-threadpool-info server
241 Retrieve server's threadpool attributes. These attributes include:
243 • minWorkers as the bottom limit to the number of active workers,
245 • maxWorkers as the top limit to the number of active workers,
247 • nWorkers as the current number of workers in the threadpool,
249 • freeWorkers as the current number of workers available for a task,
251 • prioWorkers as the current number of priority workers in the thread‐
253 pool, and
254 • jobQueueDepth as the current depth of threadpool's job queue.
256 Background
258 Each daemon server utilizes a threadpool to accomplish tasks requested
260 by clients connected to it. Every time a client request arrives to the
261 server, it checks whether there is a worker available to accomplish the
262 given task or it should create a new worker for the job (rather than
263 being destroyed, the worker becomes free once the task is finished).
264 Creating new workers, however, is only possible when the current number
265 of workers is still below the configured upper limit. In addition to
266 these 'standard' workers, a threadpool also contains a special set of
267 workers called priority workers. Their purpose is to perform tasks
268 that, unlike tasks carried out by normal workers, are within libvirt's
269 full control and libvirt guarantees that such a task cannot hang, thus
270 will always finish. An example of such a task this would be destroying
271 a domain:
272 $ virsh destroy <domain>.
274 server-threadpool-set
276 Syntax:
277 server-threadpool-set server [--min-workers count] [--max-workers count] [--priority-workers count]
279 Change threadpool attributes on a server. Only a fraction of all at‐
281 tributes as described in server-threadpool-info is supported for the
282 setter.
283 • --min-workers
285 The bottom limit to number of active workers in a threadpool.
287 • --max-workers
289 The upper limit to number of active workers in a threadpool. If used
291 in combination with option --min-workers, the value for the upper
292 limit has to be greater than the value for the bottom limit, other‐
293 wise the command results in an error.
294 • --priority-workers
296 The current number of active priority workers in a threadpool.
298 server-clients-info
300 Syntax:
301 server-clients-info server
303 Get information about the current setting of limits regarding connec‐
305 tions of new clients. This information comprises of the limits to the
306 maximum number of clients connected to server, maximum number of
307 clients waiting for authentication, in order to be connected to the
308 server, as well as the current runtime values, more specifically, the
309 current number of clients connected to server and the current number of
310 clients waiting for authentication.
311 Example:
313 # virt-admin server-clients-info libvirtd
315 nclients_max : 120
316 nclients : 3
317 nclients_unauth_max : 20
318 nclients_unauth : 0
319 server-clients-set
321 Syntax:
322 server-clients-set server [--max-clients count] [--max-unauth-clients count]
324 Set new client-related limits on server.
326 • --max-clients
328 Change the upper limit of the maximum overall number of clients con‐
330 nected to server to value count. The value for this limit has to be
331 always greater than the value of --max-unauth-clients.
332 • --max-unauth-clients
334 Change the upper limit of the maximum number of clients waiting for
336 authentication, in order to be connected to server, to value count.
337 The value for this limit has to be always lower than the value of
338 --max-clients.
339 server-update-tls
341 Syntax:
342 server-update-tls server
344 Update tls context on server.
346 • server
348 Available servers on a daemon. Currently only supports 'libvirtd' or
350 'virtproxyd'.
351
353 The following commands provide management and monitoring of clients
354 connected to one of daemon's available servers. Clients are specified
355 by their numeric ID which is obtained by listing all clients connected
356 to a specified server (see command client-list).
357 client-list
359 Syntax:
360 client-list server
362 Print a table showing the list of clients connected to <server>, also
364 providing information about transport type used on client's connection
365 (supported transports include unix, tcp, and tls), as well as providing
366 information about client's connection time (system local time is used).
367 client-info
369 Syntax:
370 client-info server client
372 Retrieve identity information about client from server. The attributes
374 returned may vary depending on the connection transport used. Trans‐
375 port-dependent attributes include local client process's pid, uid, user
376 name, and group name, as well as socket address of the remote peer, see
377 Examples below.
378 On the other hand, transport-independent attributes include client's
380 SELinux context (if enabled on the host) and SASL username (if SASL au‐
381 thentication is enabled within daemon).
382 Examples:
384 # virt-admin client-info libvirtd 1
386 id : 1
387 connection_time: 2016-05-03 13:27:04+0200
388 transport : unix
389 readonly : yes
390 unix_user_id : 0
391 unix_user_name : root
392 unix_group_id : 0
393 unix_group_name: root
394 unix_process_id: 10201
395 # virt-admin client-info libvirtd 2
397 id : 2
398 connection_time: 2016-05-03 13:30:33+0200
399 transport : tcp
400 readonly : no
401 sock_addr : 127.0.0.1:57060
402 client-disconnect
404 Syntax:
405 client-disconnect server client
407 Close a connection originating from client. The server argument speci‐
409 fies the name of the server client is currently connected to.
410
412 The following environment variables can be set to alter the behaviour
413 of virt-admin
414 • VIRT_ADMIN_DEBUG=<0 to 4>
416 Turn on verbose debugging of virt-admin commands. Valid levels are
418 • VIRT_ADMIN_DEBUG=0
420 DEBUG - Messages at ALL levels get logged
422 • VIRT_ADMIN_DEBUG=1
424 INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
426 • VIRT_ADMIN_DEBUG=2
428 NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
430 • VIRT_ADMIN_DEBUG=3
432 WARNING - Logs messages at levels WARNING and ERROR
434 • VIRT_ADMIN_DEBUG=4
436 ERROR - Messages at only ERROR level gets logged.
438 • VIRT_ADMIN_LOG_FILE=``LOGFILE``
440 The file to log virt-admin debug messages.
442 • LIBVIRT_ADMIN_DEFAULT_URI
444 The daemon whose admin server to connect to by default. Set this to a
446 URI, in the same format as accepted by the connect option. This over‐
447 rides the default URI set in any client config file.
448 • VIRT_ADMIN_HISTSIZE
450 The number of commands to remember in the command history. The de‐
452 fault value is 500.
453 • LIBVIRT_DEBUG=LEVEL
455 Turn on verbose debugging of all libvirt API calls. Valid levels are
457 • LIBVIRT_DEBUG=1
459 Messages at level DEBUG or above
461 • LIBVIRT_DEBUG=2
463 Messages at level INFO or above
465 • LIBVIRT_DEBUG=3
467 Messages at level WARNING or above
469 • LIBVIRT_DEBUG=4
471 Messages at level ERROR or above
473 For further information about debugging options consult
475 https://libvirt.org/logging.html
476
478 Please refer to the AUTHORS file distributed with libvirt.
479
481 Please report all bugs you discover. This should be done via either:
482 1. the mailing list
484 https://libvirt.org/contact.html
486 2. the bug tracker
488 https://libvirt.org/bugs.html
490 Alternatively, you may report bugs to your software distributor / ven‐
492 dor.
493
495 Copyright (C) 2015 Red Hat, Inc., and the authors listed in the libvirt
496 AUTHORS file.
497
499 virt-admin is distributed under the terms of the GNU LGPL v2+. This is
500 free software; see the source for copying conditions. There is NO war‐
501 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
502
504 virsh(1), virt-xml-validate(1), virt-host-validate(1),
505 https://libvirt.org/
506 VIRT-ADMIN(1)