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