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 daemon-timeout
234 Syntax:
235 daemon-timeout --timeout NUM
237 Sets the daemon timeout to the value of '--timeout' argument. Use
239 --timeout 0 to disable auto-shutdown of the daemon.
240
242 The following commands manipulate daemon's server internal configura‐
243 tion. The server is specified by its name.
244 server-threadpool-info
246 Syntax:
247 server-threadpool-info server
249 Retrieve server's threadpool attributes. These attributes include:
251 • minWorkers as the bottom limit to the number of active workers,
253 • maxWorkers as the top limit to the number of active workers,
255 • nWorkers as the current number of workers in the threadpool,
257 • freeWorkers as the current number of workers available for a task,
259 • prioWorkers as the current number of priority workers in the thread‐
261 pool, and
262 • jobQueueDepth as the current depth of threadpool's job queue.
264 Background
266 Each daemon server utilizes a threadpool to accomplish tasks requested
268 by clients connected to it. Every time a client request arrives to the
269 server, it checks whether there is a worker available to accomplish the
270 given task or it should create a new worker for the job (rather than
271 being destroyed, the worker becomes free once the task is finished).
272 Creating new workers, however, is only possible when the current number
273 of workers is still below the configured upper limit. In addition to
274 these 'standard' workers, a threadpool also contains a special set of
275 workers called priority workers. Their purpose is to perform tasks
276 that, unlike tasks carried out by normal workers, are within libvirt's
277 full control and libvirt guarantees that such a task cannot hang, thus
278 will always finish. An example of such a task this would be destroying
279 a domain:
280 $ virsh destroy <domain>.
282 server-threadpool-set
284 Syntax:
285 server-threadpool-set server [--min-workers count] [--max-workers count] [--priority-workers count]
287 Change threadpool attributes on a server. Only a fraction of all at‐
289 tributes as described in server-threadpool-info is supported for the
290 setter.
291 • --min-workers
293 The bottom limit to number of active workers in a threadpool.
295 • --max-workers
297 The upper limit to number of active workers in a threadpool. If used
299 in combination with option --min-workers, the value for the upper
300 limit has to be greater than the value for the bottom limit, other‐
301 wise the command results in an error.
302 • --priority-workers
304 The current number of active priority workers in a threadpool.
306 server-clients-info
308 Syntax:
309 server-clients-info server
311 Get information about the current setting of limits regarding connec‐
313 tions of new clients. This information comprises of the limits to the
314 maximum number of clients connected to server, maximum number of
315 clients waiting for authentication, in order to be connected to the
316 server, as well as the current runtime values, more specifically, the
317 current number of clients connected to server and the current number of
318 clients waiting for authentication.
319 Example:
321 # virt-admin server-clients-info libvirtd
323 nclients_max : 120
324 nclients : 3
325 nclients_unauth_max : 20
326 nclients_unauth : 0
327 server-clients-set
329 Syntax:
330 server-clients-set server [--max-clients count] [--max-unauth-clients count]
332 Set new client-related limits on server.
334 • --max-clients
336 Change the upper limit of the maximum overall number of clients con‐
338 nected to server to value count. The value for this limit has to be
339 always greater than the value of --max-unauth-clients.
340 • --max-unauth-clients
342 Change the upper limit of the maximum number of clients waiting for
344 authentication, in order to be connected to server, to value count.
345 The value for this limit has to be always lower than the value of
346 --max-clients.
347 server-update-tls
349 Syntax:
350 server-update-tls server
352 Update tls context on server.
354 • server
356 Available servers on a daemon. Currently only supports 'libvirtd' or
358 'virtproxyd'.
359
361 The following commands provide management and monitoring of clients
362 connected to one of daemon's available servers. Clients are specified
363 by their numeric ID which is obtained by listing all clients connected
364 to a specified server (see command client-list).
365 client-list
367 Syntax:
368 client-list server
370 Print a table showing the list of clients connected to <server>, also
372 providing information about transport type used on client's connection
373 (supported transports include unix, tcp, and tls), as well as providing
374 information about client's connection time (system local time is used).
375 client-info
377 Syntax:
378 client-info server client
380 Retrieve identity information about client from server. The attributes
382 returned may vary depending on the connection transport used. Trans‐
383 port-dependent attributes include local client process's pid, uid, user
384 name, and group name, as well as socket address of the remote peer, see
385 Examples below.
386 On the other hand, transport-independent attributes include client's
388 SELinux context (if enabled on the host) and SASL username (if SASL au‐
389 thentication is enabled within daemon).
390 Examples:
392 # virt-admin client-info libvirtd 1
394 id : 1
395 connection_time: 2016-05-03 13:27:04+0200
396 transport : unix
397 readonly : yes
398 unix_user_id : 0
399 unix_user_name : root
400 unix_group_id : 0
401 unix_group_name: root
402 unix_process_id: 10201
403 # virt-admin client-info libvirtd 2
405 id : 2
406 connection_time: 2016-05-03 13:30:33+0200
407 transport : tcp
408 readonly : no
409 sock_addr : 127.0.0.1:57060
410 client-disconnect
412 Syntax:
413 client-disconnect server client
415 Close a connection originating from client. The server argument speci‐
417 fies the name of the server client is currently connected to.
418
420 The following environment variables can be set to alter the behaviour
421 of virt-admin
422 • VIRT_ADMIN_DEBUG=<0 to 4>
424 Turn on verbose debugging of virt-admin commands. Valid levels are
426 • VIRT_ADMIN_DEBUG=0
428 DEBUG - Messages at ALL levels get logged
430 • VIRT_ADMIN_DEBUG=1
432 INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
434 • VIRT_ADMIN_DEBUG=2
436 NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
438 • VIRT_ADMIN_DEBUG=3
440 WARNING - Logs messages at levels WARNING and ERROR
442 • VIRT_ADMIN_DEBUG=4
444 ERROR - Messages at only ERROR level gets logged.
446 • VIRT_ADMIN_LOG_FILE=``LOGFILE``
448 The file to log virt-admin debug messages.
450 • LIBVIRT_ADMIN_DEFAULT_URI
452 The daemon whose admin server to connect to by default. Set this to a
454 URI, in the same format as accepted by the connect option. This over‐
455 rides the default URI set in any client config file.
456 • VIRT_ADMIN_HISTSIZE
458 The number of commands to remember in the command history. The de‐
460 fault value is 500.
461 • LIBVIRT_DEBUG=LEVEL
463 Turn on verbose debugging of all libvirt API calls. Valid levels are
465 • LIBVIRT_DEBUG=1
467 Messages at level DEBUG or above
469 • LIBVIRT_DEBUG=2
471 Messages at level INFO or above
473 • LIBVIRT_DEBUG=3
475 Messages at level WARNING or above
477 • LIBVIRT_DEBUG=4
479 Messages at level ERROR or above
481 For further information about debugging options consult
483 https://libvirt.org/logging.html
484
486 Please refer to the AUTHORS file distributed with libvirt.
487
489 Please report all bugs you discover. This should be done via either:
490 1. the mailing list
492 https://libvirt.org/contact.html
494 2. the bug tracker
496 https://libvirt.org/bugs.html
498 Alternatively, you may report bugs to your software distributor / ven‐
500 dor.
501
503 Copyright (C) 2015 Red Hat, Inc., and the authors listed in the libvirt
504 AUTHORS file.
505
507 virt-admin is distributed under the terms of the GNU LGPL v2+. This is
508 free software; see the source for copying conditions. There is NO war‐
509 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
510
512 virsh(1), virt-xml-validate(1), virt-host-validate(1),
513 https://libvirt.org/
514 VIRT-ADMIN(1)