virt-admin(1)

1VIRT-ADMIN(1)               Virtualization Support               VIRT-ADMIN(1)
2
3
4

NAME

6       virt-admin - daemon administration interface
7

SYNOPSIS

9       virt-admin [OPTION]... [COMMAND_STRING]
10
11       virt-admin [OPTION]... COMMAND [ARG]...
12

DESCRIPTION

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
19       The basic structure of most virt-admin usage is:
20
21         virt-admin [OPTION]... <command> [ARG]...
22
23       Where command is one of the commands listed below.
24
25       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 between commands.  Within COMMAND_STRING, virt-
30       admin understands the same single, double, and backslash escapes as the
31       shell, although you must add another layer of shell escaping in
32       creating the single shell argument.  If no command is given in the
33       command line, virt-admin will then start a minimal interpreter waiting
34       for your commands, and the quit command will then exit the program.
35
36       The virt-admin program understands the following OPTIONS.
37
38       -c, --connect URI
39           Connect to the specified URI, as if by the connect command, instead
40           of the default connection.
41
42       -d, --debug LEVEL
43           Enable debug messages at integer LEVEL and above.  LEVEL can range
44           from 0 to 4 (default).  See the documentation of VIRT_ADMIN_DEBUG
45           environment variable below for the description of each LEVEL.
46
47       -h, --help
48           Ignore all other arguments, and behave as if the help command were
49           given instead.
50
51       -l, --log FILE
52           Output logging details to FILE.
53
54       -q, --quiet
55           Avoid extra informational messages.
56
57       -v, --version[=short]
58           Ignore all other arguments, and prints the version of the libvirt
59           library virt-admin is coming from
60
61       -V, --version=long
62           Ignore all other arguments, and prints the version of the libvirt
63           library virt-admin is coming from.
64

NOTES

66       Running virt-admin requires root privileges due to the communications
67       channels used to talk to the daemon. Consider changing the
68       unix_sock_group ownership setting to grant access to specific set of
69       users or modifying unix_sock_rw_perms permissions. Daemon configuration
70       file provides more information about setting permissions.
71

GENERIC COMMANDS

73       The following commands are generic.
74
75       help [command-or-group]
76           This lists each of the virt-admin commands.  When used without
77           options, all commands are listed, one per line, grouped into
78           related categories, displaying the keyword for each group.
79
80           To display detailed information for a specific command, use its
81           name as the option.
82
83       quit, exit
84           quit this interactive terminal
85
86       version
87           Will print out the version info about which libvirt library was
88           this client built from. As opposed to virsh client, the output
89           already includes the version of the daemon.
90
91           Example
92
93            $ virt-admin version
94            Compiled against library: libvirt 1.2.21
95            Using library: libvirt 1.2.21
96            Running against daemon: 1.2.20
97
98       cd [directory]
99           Will change current directory to directory.  The default directory
100           for the cd command is the home directory or, if there is no HOME
101           variable in the environment, the root directory.
102
103           This command is only available in interactive mode.
104
105       pwd Will print the current directory.
106
107       connect [URI]
108           (Re)-Connect to a daemon's administrating server. The URI parameter
109           specifies how to connect to the administrating server.  If
110           LIBVIRT_ADMIN_DEFAULT_URI or uri_default (see below) were set,
111           connect is automatically issued every time a command that requires
112           an active connection is executed. Note that this only applies if
113           there is no connection at all or there is an inactive one.
114
115           To find the currently used URI, check the uri command documented
116           below.
117
118       uri Prints the administrating server canonical URI, can be useful in
119           shell mode. If no uri was specified, neither
120           LIBVIRT_ADMIN_DEFAULT_URI environment variable nor uri_default
121           option (libvirt-admin.conf) were set, libvirtd:///system is used.
122

DAEMON COMMANDS

124       The following commands allow to monitor the daemon's state as well as
125       directly change its internal configuration.
126
127       server-list
128           Lists all manageable servers contained within the daemon the client
129           is currently connected to.
130
131       daemon-log-filters [--filters string]
132           When run without arguments, this returns the currently defined set
133           of logging filters. Providing an argument will cause the command to
134           define a new set of logging filters.
135
136           --filters
137               Define a new set of logging filters where multiple filters are
138               delimited by space. Each filter must conform to the form
139               described in detail by /etc/libvirt/libvirtd.conf (section
140               'Logging filters').
141
142           Example
143
144               To define a filter which suppresses all e.g. 'virObjectUnref' DEBUG
145               messages, use the following:
146
147                   $ virt-admin daemon-log-filters "4:util.object"
148
149               (Note the '.' symbol which can be used to more fine-grained filters tailored
150                to specific modules, in contrast, to affect the whole directory containing
151                several modules this would become "4:util"):
152
153       daemon-log-outputs [--outputs string]
154           When run without arguments, this returns the currently defined set
155           of logging outputs. Providing an argument will cause the command to
156           define a new set of logging outputs.
157
158           --outputs
159               Define a new set of logging outputs where multiple outputs are
160               delimited by space. Each output must conform to the form
161               described in detail by /etc/libvirt/libvirtd.conf (section
162               'Logging outputs').
163
164           Example
165
166               To replace the current setting for logging outputs with one that writes to
167               a file while logging errors only, the following could be used:
168
169                   $ virt-admin daemon-log-outputs "4:file:<absolute_path_to_the_file>"
170
171               To define multiple outputs at once they need to be delimited by spaces:
172
173                   $ virt-admin daemon-log-outputs "4:stderr 2:syslog:<msg_ident>"
174

SERVER COMMANDS

176       The following commands manipulate daemon's server internal
177       configuration.  The server is specified by its name.
178
179       server-threadpool-info server
180           Retrieve server's threadpool attributes. These attributes include:
181
182           minWorkers as the bottom limit to the number of active workers,
183           maxWorkers as the top limit to the number of active workers,
184           nWorkers as the current number of workers in the threadpool,
185           freeWorkers as the current number of workers available for a task,
186           prioWorkers as the current number of priority workers in the
187           threadpool, and
188           jobQueueDepth as the current depth of threadpool's job queue.
189
190           Background
191
192           Each daemon server utilizes a threadpool to accomplish tasks
193           requested by clients connected to it. Every time a client request
194           arrives to the server, it checks whether there is a worker
195           available to accomplish the given task or it should create a new
196           worker for the job (rather than being destroyed, the worker becomes
197           free once the task is finished). Creating new workers, however, is
198           only possible when the current number of workers is still below the
199           configured upper limit.
200
201           In addition to these 'standard' workers, a threadpool also contains
202           a special set of workers called priority workers. Their purpose is
203           to perform tasks that, unlike tasks carried out by normal workers,
204           are within libvirt's full control and libvirt guarantees that such
205           a task cannot hang, thus will always finish. An example of such a
206           task this would be destroying a domain:
207               $ virsh destroy <domain>.
208
209       server-threadpool-set server [--min-workers count] [--max-workers
210       count] [--priority-workers count]
211           Change threadpool attributes on a server. Only a fraction of all
212           attributes as described in server-threadpool-info is supported for
213           the setter.
214
215           --min-workers
216               The bottom limit to number of active workers in a threadpool.
217
218           --max-workers
219               The upper limit to number of active workers in a threadpool. If
220               used in combination with option --min-workers, the value for
221               the upper limit has to be greater than the value for the bottom
222               limit, otherwise the command results in an error.
223
224           --priority-workers
225               The current number of active priority workers in a threadpool.
226
227       server-clients-info server
228           Get information about the current setting of limits regarding
229           connections of new clients. This information comprises of the
230           limits to the maximum number of clients connected to server,
231           maximum number of clients waiting for authentication, in order to
232           be connected to the server, as well as the current runtime values,
233           more specifically, the current number of clients connected to
234           server and the current number of clients waiting for
235           authentication.
236
237           Example
238               # virt-admin server-clients-info libvirtd
239               nclients_max        : 120
240               nclients            : 3
241               nclients_unauth_max : 20
242               nclients_unauth     : 0
243
244       server-clients-set server [--max-clients count] [--max-unauth-clients
245       count]
246           Set new client-related limits on server.
247
248           --max-clients
249               Change the upper limit of the maximum overall number of clients
250               connected to server to value count. The value for this limit
251               has to be always greater than the value of
252               --max-unauth-clients.
253
254           --max-unauth-clients
255               Change the upper limit of the maximum number of clients waiting
256               for authentication, in order to be connected to server, to
257               value count.  The value for this limit has to be always lower
258               than the value of --max-clients.
259

CLIENT COMMANDS

261       The following commands provide management and monitoring of clients
262       connected to one of daemon's available servers. Clients are specified
263       by their numeric ID which is obtained by listing all clients connected
264       to a specified server (see command client-list).
265
266       client-list server
267           Print a table showing the list of clients connected to <server>,
268           also providing information about transport type used on client's
269           connection (supported transports include unix, tcp, and tls), as
270           well as providing information about client's connection time
271           (system local time is used).
272
273       client-info server client
274           Retrieve identity information about client from server. The
275           attributes returned may vary depending on the connection transport
276           used.  Transport-dependent attributes include local client
277           process's pid, uid, user name, and group name, as well as socket
278           address of the remote peer, see Examples below.
279
280           On the other hand, transport-independent attributes include
281           client's SELinux context (if enabled on the host) and SASL username
282           (if SASL authentication is enabled within daemon).
283
284           Examples
285
286            # virt-admin client-info libvirtd 1
287            id             : 1
288            connection_time: 2016-05-03 13:27:04+0200
289            transport      : unix
290            readonly       : yes
291            unix_user_id   : 0
292            unix_user_name : root
293            unix_group_id  : 0
294            unix_group_name: root
295            unix_process_id: 10201
296
297            # virt-admin client-info libvirtd 2
298            id             : 2
299            connection_time: 2016-05-03 13:30:33+0200
300            transport      : tcp
301            readonly       : no
302            sock_addr      : 127.0.0.1:57060
303
304       client-disconnect server client
305           Close a connection originating from client. The server argument
306           specifies the name of the server client is currently connected to.
307

ENVIRONMENT

309       The following environment variables can be set to alter the behaviour
310       of "virt-admin"
311
312       VIRT_ADMIN_DEBUG=<0 to 4>
313           Turn on verbose debugging of virt-admin commands. Valid levels are
314
315           ·   VIRT_ADMIN_DEBUG=0
316
317               DEBUG - Messages at ALL levels get logged
318
319           ·   VIRT_ADMIN_DEBUG=1
320
321               INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
322
323           ·   VIRT_ADMIN_DEBUG=2
324
325               NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
326
327           ·   VIRT_ADMIN_DEBUG=3
328
329               WARNING - Logs messages at levels WARNING and ERROR
330
331           ·   VIRT_ADMIN_DEBUG=4
332
333               ERROR - Messages at only ERROR level gets logged.
334
335       VIRT_ADMIN_LOG_FILE="LOGFILE"
336           The file to log virt-admin debug messages.
337
338       LIBVIRT_ADMIN_DEFAULT_URI
339           The daemon whose admin server to connect to by default. Set this to
340           a URI, in the same format as accepted by the connect option. This
341           overrides the default URI set in any client config file.
342
343       VIRT_ADMIN_HISTSIZE
344           The number of commands to remember in the command  history.  The
345           default value is 500.
346
347       LIBVIRT_DEBUG=LEVEL
348           Turn on verbose debugging of all libvirt API calls. Valid levels
349           are
350
351           ·   LIBVIRT_DEBUG=1
352
353               Messages at level DEBUG or above
354
355           ·   LIBVIRT_DEBUG=2
356
357               Messages at level INFO or above
358
359           ·   LIBVIRT_DEBUG=3
360
361               Messages at level WARNING or above
362
363           ·   LIBVIRT_DEBUG=4
364
365               Messages at level ERROR or above
366
367           For further information about debugging options consult
368           <https://libvirt.org/logging.html>
369

BUGS

371       Report any bugs discovered to the libvirt community via the mailing
372       list <https://libvirt.org/contact.html> or bug tracker
373       <https://libvirt.org/bugs.html>.  Alternatively report bugs to your
374       software distributor / vendor.
375

AUTHORS

377         Please refer to the AUTHORS file distributed with libvirt.
378
379         Based on the virsh man page.
380

COPYRIGHT

382       Copyright (C) 2015 Red Hat, Inc., and the authors listed in the libvirt
383       AUTHORS file.
384

LICENSE

386       virt-admin is distributed under the terms of the GNU LGPL v2+.  This is
387       free software; see the source for copying conditions. There is NO
388       warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
389       PURPOSE
390