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
15 modifying the libvirt daemon configuration at runtime, changing daemon
16 behaviour as well as for monitoring and managing all clients connected
17 to 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
25 unrecognized 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
29 COMMAND_STRING which is a single shell argument consisting of multiple
30 COMMAND actions and their arguments joined with whitespace and
31 separated by semicolons or newlines between commands, where unquoted
32 backslash-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
35 creating 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
44 of the default connection.
45 -d, --debug LEVEL
47 Enable debug messages at integer LEVEL and above. LEVEL can range
48 from 0 to 4 (default). See the documentation of VIRT_ADMIN_DEBUG
49 environment variable below for the description of each LEVEL.
50 -h, --help
52 Ignore all other arguments, and behave as if the help command were
53 given instead.
54 -l, --log FILE
56 Output logging details to FILE.
57 -q, --quiet
59 Avoid extra informational messages.
60 -v, --version[=short]
62 Ignore all other arguments, and prints the version of the libvirt
63 library virt-admin is coming from
64 -V, --version=long
66 Ignore all other arguments, and prints the version of the libvirt
67 library virt-admin is coming from.
68
70 Running virt-admin requires root privileges due to the communications
71 channels used to talk to the daemon. Consider changing the
72 unix_sock_group ownership setting to grant access to specific set of
73 users or modifying unix_sock_rw_perms permissions. Daemon configuration
74 file provides more information about setting permissions.
75
77 The following commands are generic.
78 help [command-or-group]
80 This lists each of the virt-admin commands. When used without
81 options, all commands are listed, one per line, grouped into
82 related categories, displaying the keyword for each group.
83 To display detailed information for a specific command, use its
85 name as the option.
86 quit, exit
88 quit this interactive terminal
89 version
91 Will print out the version info about which libvirt library was
92 this client built from. As opposed to virsh client, the output
93 already includes the version of the daemon.
94 Example
96 $ virt-admin version
98 Compiled against library: libvirt 1.2.21
99 Using library: libvirt 1.2.21
100 Running against daemon: 1.2.20
101 cd [directory]
103 Will change current directory to directory. The default directory
104 for the cd command is the home directory or, if there is no HOME
105 variable in the environment, the root directory.
106 This command is only available in interactive mode.
108 pwd Will print the current directory.
110 connect [URI]
112 (Re)-Connect to a daemon's administrating server. The URI parameter
113 specifies how to connect to the administrating server. If
114 LIBVIRT_ADMIN_DEFAULT_URI or uri_default (see below) were set,
115 connect is automatically issued every time a command that requires
116 an active connection is executed. Note that this only applies if
117 there is no connection at all or there is an inactive one.
118 To find the currently used URI, check the uri command documented
120 below.
121 uri Prints the administrating server canonical URI, can be useful in
123 shell mode. If no uri was specified, neither
124 LIBVIRT_ADMIN_DEFAULT_URI environment variable nor uri_default
125 option (libvirt-admin.conf) were set, libvirtd:///system is used.
126
128 The following commands allow one to monitor the daemon's state as well
129 as directly change its internal configuration.
130 server-list
132 Lists all manageable servers contained within the daemon the client
133 is currently connected to.
134 daemon-log-filters [--filters string]
136 When run without arguments, this returns the currently defined set
137 of logging filters. Providing an argument will cause the command to
138 define a new set of logging filters.
139 --filters
141 Define a new set of logging filters where multiple filters are
142 delimited by space. Each filter must conform to the form
143 described in detail by /etc/libvirt/libvirtd.conf (section
144 'Logging filters').
145 Example
147 To define a filter which suppresses all e.g. 'virObjectUnref' DEBUG
149 messages, use the following:
150 $ virt-admin daemon-log-filters "4:util.object"
152 (Note the '.' symbol which can be used to more fine-grained filters tailored
154 to specific modules, in contrast, to affect the whole directory containing
155 several modules this would become "4:util"):
156 daemon-log-outputs [--outputs string]
158 When run without arguments, this returns the currently defined set
159 of logging outputs. Providing an argument will cause the command to
160 define a new set of logging outputs.
161 --outputs
163 Define a new set of logging outputs where multiple outputs are
164 delimited by space. Each output must conform to the form
165 described in detail by /etc/libvirt/libvirtd.conf (section
166 'Logging outputs').
167 Example
169 To replace the current setting for logging outputs with one that writes to
171 a file while logging errors only, the following could be used:
172 $ virt-admin daemon-log-outputs "4:file:<absolute_path_to_the_file>"
174 To define multiple outputs at once they need to be delimited by spaces:
176 $ virt-admin daemon-log-outputs "4:stderr 2:syslog:<msg_ident>"
178
180 The following commands manipulate daemon's server internal
181 configuration. The server is specified by its name.
182 server-threadpool-info server
184 Retrieve server's threadpool attributes. These attributes include:
185 minWorkers as the bottom limit to the number of active workers,
187 maxWorkers as the top limit to the number of active workers,
188 nWorkers as the current number of workers in the threadpool,
189 freeWorkers as the current number of workers available for a task,
190 prioWorkers as the current number of priority workers in the
191 threadpool, and
192 jobQueueDepth as the current depth of threadpool's job queue.
193 Background
195 Each daemon server utilizes a threadpool to accomplish tasks
197 requested by clients connected to it. Every time a client request
198 arrives to the server, it checks whether there is a worker
199 available to accomplish the given task or it should create a new
200 worker for the job (rather than being destroyed, the worker becomes
201 free once the task is finished). Creating new workers, however, is
202 only possible when the current number of workers is still below the
203 configured upper limit.
204 In addition to these 'standard' workers, a threadpool also contains
206 a special set of workers called priority workers. Their purpose is
207 to perform tasks that, unlike tasks carried out by normal workers,
208 are within libvirt's full control and libvirt guarantees that such
209 a task cannot hang, thus will always finish. An example of such a
210 task this would be destroying a domain:
211 $ virsh destroy <domain>.
212 server-threadpool-set server [--min-workers count] [--max-workers
214 count] [--priority-workers count]
215 Change threadpool attributes on a server. Only a fraction of all
216 attributes as described in server-threadpool-info is supported for
217 the setter.
218 --min-workers
220 The bottom limit to number of active workers in a threadpool.
221 --max-workers
223 The upper limit to number of active workers in a threadpool. If
224 used in combination with option --min-workers, the value for
225 the upper limit has to be greater than the value for the bottom
226 limit, otherwise the command results in an error.
227 --priority-workers
229 The current number of active priority workers in a threadpool.
230 server-clients-info server
232 Get information about the current setting of limits regarding
233 connections of new clients. This information comprises of the
234 limits to the maximum number of clients connected to server,
235 maximum number of clients waiting for authentication, in order to
236 be connected to the server, as well as the current runtime values,
237 more specifically, the current number of clients connected to
238 server and the current number of clients waiting for
239 authentication.
240 Example
242 # virt-admin server-clients-info libvirtd
243 nclients_max : 120
244 nclients : 3
245 nclients_unauth_max : 20
246 nclients_unauth : 0
247 server-clients-set server [--max-clients count] [--max-unauth-clients
249 count]
250 Set new client-related limits on server.
251 --max-clients
253 Change the upper limit of the maximum overall number of clients
254 connected to server to value count. The value for this limit
255 has to be always greater than the value of
256 --max-unauth-clients.
257 --max-unauth-clients
259 Change the upper limit of the maximum number of clients waiting
260 for authentication, in order to be connected to server, to
261 value count. The value for this limit has to be always lower
262 than the value of --max-clients.
263
265 The following commands provide management and monitoring of clients
266 connected to one of daemon's available servers. Clients are specified
267 by their numeric ID which is obtained by listing all clients connected
268 to a specified server (see command client-list).
269 client-list server
271 Print a table showing the list of clients connected to <server>,
272 also providing information about transport type used on client's
273 connection (supported transports include unix, tcp, and tls), as
274 well as providing information about client's connection time
275 (system local time is used).
276 client-info server client
278 Retrieve identity information about client from server. The
279 attributes returned may vary depending on the connection transport
280 used. Transport-dependent attributes include local client
281 process's pid, uid, user name, and group name, as well as socket
282 address of the remote peer, see Examples below.
283 On the other hand, transport-independent attributes include
285 client's SELinux context (if enabled on the host) and SASL username
286 (if SASL authentication is enabled within daemon).
287 Examples
289 # virt-admin client-info libvirtd 1
291 id : 1
292 connection_time: 2016-05-03 13:27:04+0200
293 transport : unix
294 readonly : yes
295 unix_user_id : 0
296 unix_user_name : root
297 unix_group_id : 0
298 unix_group_name: root
299 unix_process_id: 10201
300 # virt-admin client-info libvirtd 2
302 id : 2
303 connection_time: 2016-05-03 13:30:33+0200
304 transport : tcp
305 readonly : no
306 sock_addr : 127.0.0.1:57060
307 client-disconnect server client
309 Close a connection originating from client. The server argument
310 specifies the name of the server client is currently connected to.
311
313 The following environment variables can be set to alter the behaviour
314 of "virt-admin"
315 VIRT_ADMIN_DEBUG=<0 to 4>
317 Turn on verbose debugging of virt-admin commands. Valid levels are
318 · VIRT_ADMIN_DEBUG=0
320 DEBUG - Messages at ALL levels get logged
322 · VIRT_ADMIN_DEBUG=1
324 INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
326 · VIRT_ADMIN_DEBUG=2
328 NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
330 · VIRT_ADMIN_DEBUG=3
332 WARNING - Logs messages at levels WARNING and ERROR
334 · VIRT_ADMIN_DEBUG=4
336 ERROR - Messages at only ERROR level gets logged.
338 VIRT_ADMIN_LOG_FILE="LOGFILE"
340 The file to log virt-admin debug messages.
341 LIBVIRT_ADMIN_DEFAULT_URI
343 The daemon whose admin server to connect to by default. Set this to
344 a URI, in the same format as accepted by the connect option. This
345 overrides the default URI set in any client config file.
346 VIRT_ADMIN_HISTSIZE
348 The number of commands to remember in the command history. The
349 default value is 500.
350 LIBVIRT_DEBUG=LEVEL
352 Turn on verbose debugging of all libvirt API calls. Valid levels
353 are
354 · LIBVIRT_DEBUG=1
356 Messages at level DEBUG or above
358 · LIBVIRT_DEBUG=2
360 Messages at level INFO or above
362 · LIBVIRT_DEBUG=3
364 Messages at level WARNING or above
366 · LIBVIRT_DEBUG=4
368 Messages at level ERROR or above
370 For further information about debugging options consult
372 <https://libvirt.org/logging.html>
373
375 Report any bugs discovered to the libvirt community via the mailing
376 list <https://libvirt.org/contact.html> or bug tracker
377 <https://libvirt.org/bugs.html>. Alternatively report bugs to your
378 software distributor / vendor.
379
381 Please refer to the AUTHORS file distributed with libvirt.
382 Based on the virsh man page.
384
386 Copyright (C) 2015 Red Hat, Inc., and the authors listed in the libvirt
387 AUTHORS file.
388
390 virt-admin is distributed under the terms of the GNU LGPL v2+. This is
391 free software; see the source for copying conditions. There is NO
392 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
393 PURPOSE
394
396 virsh(1), virt-xml-validate(1), virt-host-validate(1),
397 <https://libvirt.org/>
398libvirt-5.3.0 2019-04-27 VIRT-ADMIN(1)