.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "VIRT-ADMIN 1" .TH VIRT-ADMIN 1 "2017-10-30" "libvirt-3.9.0" "Virtualization Support" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" virt\-admin \- daemon administration interface .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBvirt-admin\fR [\fI\s-1OPTION\s0\fR]... [\fI\s-1COMMAND_STRING\s0\fR] .PP \&\fBvirt-admin\fR [\fI\s-1OPTION\s0\fR]... \fI\s-1COMMAND\s0\fR [\fI\s-1ARG\s0\fR]... .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fBvirt-admin\fR program is the main administration interface for modifying the libvirt daemon configuration at runtime, changing daemon behaviour as well as for monitoring and managing all clients connected to the daemon. .PP The basic structure of most virt-admin usage is: .PP .Vb 1 \& virt\-admin [OPTION]... [ARG]... .Ve .PP Where \fIcommand\fR is one of the commands listed below. .PP The \fBvirt-admin\fR program can be used either to run one \fI\s-1COMMAND\s0\fR by giving the command and its arguments on the shell command line, or a \fI\s-1COMMAND_STRING\s0\fR which is a single shell argument consisting of multiple \fI\s-1COMMAND\s0\fR actions and their arguments joined with whitespace, and separated by semicolons between commands. Within \fI\s-1COMMAND_STRING\s0\fR, virt-admin understands the same single, double, and backslash escapes as the shell, although you must add another layer of shell escaping in creating the single shell argument. If no command is given in the command line, \fBvirt-admin\fR will then start a minimal interpreter waiting for your commands, and the \fBquit\fR command will then exit the program. .PP The \fBvirt-admin\fR program understands the following \fI\s-1OPTIONS\s0\fR. .IP "\fB\-c\fR, \fB\-\-connect\fR \fI\s-1URI\s0\fR" 4 .IX Item "-c, --connect URI" Connect to the specified \fI\s-1URI\s0\fR, as if by the \fBconnect\fR command, instead of the default connection. .IP "\fB\-d\fR, \fB\-\-debug\fR \fI\s-1LEVEL\s0\fR" 4 .IX Item "-d, --debug LEVEL" Enable debug messages at integer \fI\s-1LEVEL\s0\fR and above. \fI\s-1LEVEL\s0\fR can range from 0 to 4 (default). See the documentation of \fB\s-1VIRT_ADMIN_DEBUG\s0\fR environment variable below for the description of each \fI\s-1LEVEL\s0\fR. .IP "\fB\-h\fR, \fB\-\-help\fR" 4 .IX Item "-h, --help" Ignore all other arguments, and behave as if the \fBhelp\fR command were given instead. .IP "\fB\-l\fR, \fB\-\-log\fR \fI\s-1FILE\s0\fR" 4 .IX Item "-l, --log FILE" Output logging details to \fI\s-1FILE\s0\fR. .IP "\fB\-q\fR, \fB\-\-quiet\fR" 4 .IX Item "-q, --quiet" Avoid extra informational messages. .IP "\fB\-v\fR, \fB\-\-version[=short]\fR" 4 .IX Item "-v, --version[=short]" Ignore all other arguments, and prints the version of the libvirt library virt-admin is coming from .IP "\fB\-V\fR, \fB\-\-version=long\fR" 4 .IX Item "-V, --version=long" Ignore all other arguments, and prints the version of the libvirt library virt-admin is coming from. .SH "NOTES" .IX Header "NOTES" Running \fBvirt-admin\fR requires root privileges due to the communications channels used to talk to the daemon. Consider changing the \&\fIunix_sock_group\fR ownership setting to grant access to specific set of users or modifying \fIunix_sock_rw_perms\fR permissions. Daemon configuration file provides more information about setting permissions. .SH "GENERIC COMMANDS" .IX Header "GENERIC COMMANDS" The following commands are generic. .IP "\fBhelp\fR [\fIcommand-or-group\fR]" 4 .IX Item "help [command-or-group]" This lists each of the virt-admin commands. When used without options, all commands are listed, one per line, grouped into related categories, displaying the keyword for each group. .Sp To display detailed information for a specific command, use its name as the option. .IP "\fBquit\fR, \fBexit\fR" 4 .IX Item "quit, exit" quit this interactive terminal .IP "\fBversion\fR" 4 .IX Item "version" Will print out the version info about which libvirt library was this client built from. As opposed to \fIvirsh\fR client, the output already includes the version of the daemon. .Sp \&\fBExample\fR .Sp .Vb 4 \& $ virt\-admin version \& Compiled against library: libvirt 1.2.21 \& Using library: libvirt 1.2.21 \& Running against daemon: 1.2.20 .Ve .IP "\fBcd\fR [\fIdirectory\fR]" 4 .IX Item "cd [directory]" Will change current directory to \fIdirectory\fR. The default directory for the \fBcd\fR command is the home directory or, if there is no \fI\s-1HOME\s0\fR variable in the environment, the root directory. .Sp This command is only available in interactive mode. .IP "\fBpwd\fR" 4 .IX Item "pwd" Will print the current directory. .IP "\fBconnect\fR [\fI\s-1URI\s0\fR]" 4 .IX Item "connect [URI]" (Re)\-Connect to a daemon's administrating server. The \fI\s-1URI\s0\fR parameter specifies how to connect to the administrating server. If \fI\s-1LIBVIRT_ADMIN_DEFAULT_URI\s0\fR or \fIuri_default\fR (see below) were set, \&\fIconnect\fR is automatically issued every time a command that requires an active connection is executed. Note that this only applies if there is no connection at all or there is an inactive one. .Sp To find the currently used \s-1URI,\s0 check the \fIuri\fR command documented below. .IP "\fBuri\fR" 4 .IX Item "uri" Prints the administrating server canonical \s-1URI,\s0 can be useful in shell mode. If no \fIuri\fR was specified, neither \fI\s-1LIBVIRT_ADMIN_DEFAULT_URI\s0\fR environment variable nor \fIuri_default\fR option (libvirt\-admin.conf) were set, libvirtd:///system is used. .SH "DAEMON COMMANDS" .IX Header "DAEMON COMMANDS" The following commands allow to monitor the daemon's state as well as directly change its internal configuration. .IP "\fBserver-list\fR" 4 .IX Item "server-list" Lists all manageable servers contained within the daemon the client is currently connected to. .IP "\fBdaemon-log-filters\fR [\fI\-\-filters\fR \fBstring\fR]" 4 .IX Item "daemon-log-filters [--filters string]" When run without arguments, this returns the currently defined set of logging filters. Providing an argument will cause the command to define a new set of logging filters. .RS 4 .IP "\fI\-\-filters\fR" 4 .IX Item "--filters" Define a new set of logging filters where multiple filters are delimited by space. Each filter must conform to the form described in detail by \&\fI/etc/libvirt/libvirtd.conf\fR (section 'Logging filters'). .RE .RS 4 .Sp \&\fBExample\fR .Sp .Vb 2 \& To define a filter which suppresses all e.g. \*(AqvirObjectUnref\*(Aq DEBUG \& messages, use the following: \& \& $ virt\-admin daemon\-log\-filters "4:util.object" \& \& (Note the \*(Aq.\*(Aq symbol which can be used to more fine\-grained filters tailored \& to specific modules, in contrast, to affect the whole directory containing \& several modules this would become "4:util"): .Ve .RE .IP "\fBdaemon-log-outputs\fR [\fI\-\-outputs\fR \fBstring\fR]" 4 .IX Item "daemon-log-outputs [--outputs string]" When run without arguments, this returns the currently defined set of logging outputs. Providing an argument will cause the command to define a new set of logging outputs. .RS 4 .IP "\fI\-\-outputs\fR" 4 .IX Item "--outputs" Define a new set of logging outputs where multiple outputs are delimited by space. Each output must conform to the form described in detail by \&\fI/etc/libvirt/libvirtd.conf\fR (section 'Logging outputs'). .RE .RS 4 .Sp \&\fBExample\fR .Sp .Vb 2 \& To replace the current setting for logging outputs with one that writes to \& a file while logging errors only, the following could be used: \& \& $ virt\-admin daemon\-log\-outputs "4:file:" \& \& To define multiple outputs at once they need to be delimited by spaces: \& \& $ virt\-admin daemon\-log\-outputs "4:stderr 2:syslog:" .Ve .RE .SH "SERVER COMMANDS" .IX Header "SERVER COMMANDS" The following commands manipulate daemon's server internal configuration. The \fIserver\fR is specified by its name. .IP "\fBserver-threadpool-info\fR \fIserver\fR" 4 .IX Item "server-threadpool-info server" Retrieve server's threadpool attributes. These attributes include: .RS 4 .IP "\fIminWorkers\fR as the bottom limit to the number of active workers," 4 .IX Item "minWorkers as the bottom limit to the number of active workers," .PD 0 .IP "\fImaxWorkers\fR as the top limit to the number of active workers," 4 .IX Item "maxWorkers as the top limit to the number of active workers," .IP "\fInWorkers\fR as the current number of workers in the threadpool," 4 .IX Item "nWorkers as the current number of workers in the threadpool," .IP "\fIfreeWorkers\fR as the current number of workers available for a task," 4 .IX Item "freeWorkers as the current number of workers available for a task," .IP "\fIprioWorkers\fR as the current number of priority workers in the threadpool, and" 4 .IX Item "prioWorkers as the current number of priority workers in the threadpool, and" .IP "\fIjobQueueDepth\fR as the current depth of threadpool's job queue." 4 .IX Item "jobQueueDepth as the current depth of threadpool's job queue." .RE .RS 4 .PD .Sp \&\fBBackground\fR .Sp Each daemon server utilizes a threadpool to accomplish tasks requested by clients connected to it. Every time a client request arrives to the server, it checks whether there is a worker available to accomplish the given task or it should create a new worker for the job (rather than being destroyed, the worker becomes free once the task is finished). Creating new workers, however, is only possible when the current number of workers is still below the configured upper limit. .Sp In addition to these 'standard' workers, a threadpool also contains a special set of workers called \fIpriority\fR workers. Their purpose is to perform tasks that, unlike tasks carried out by normal workers, are within libvirt's full control and libvirt guarantees that such a task cannot hang, thus will always finish. An example of such a task this would be destroying a domain: $ virsh destroy . .RE .IP "\fBserver-threadpool-set\fR \fIserver\fR [\fI\-\-min\-workers\fR \fBcount\fR] [\fI\-\-max\-workers\fR \fBcount\fR] [\fI\-\-priority\-workers\fR \fBcount\fR]" 4 .IX Item "server-threadpool-set server [--min-workers count] [--max-workers count] [--priority-workers count]" Change threadpool attributes on a server. Only a fraction of all attributes as described in \fIserver-threadpool-info\fR is supported for the setter. .RS 4 .IP "\fI\-\-min\-workers\fR" 4 .IX Item "--min-workers" The bottom limit to number of active workers in a threadpool. .IP "\fI\-\-max\-workers\fR" 4 .IX Item "--max-workers" The upper limit to number of active workers in a threadpool. If used in combination with option \fI\-\-min\-workers\fR, the value for the upper limit has to be greater than the value for the bottom limit, otherwise the command results in an error. .IP "\fI\-\-priority\-workers\fR" 4 .IX Item "--priority-workers" The current number of active priority workers in a threadpool. .RE .RS 4 .RE .IP "\fBserver-clients-info\fR \fIserver\fR" 4 .IX Item "server-clients-info server" Get information about the current setting of limits regarding connections of new clients. This information comprises of the limits to the maximum number of clients connected to \fIserver\fR, maximum number of clients waiting for authentication, in order to be connected to the server, as well as the current runtime values, more specifically, the current number of clients connected to \&\fIserver\fR and the current number of clients waiting for authentication. .Sp \&\fBExample\fR # virt-admin server-clients-info libvirtd nclients_max : 120 nclients : 3 nclients_unauth_max : 20 nclients_unauth : 0 .IP "\fBserver-clients-set\fR \fIserver\fR [\fI\-\-max\-clients\fR \fBcount\fR] [\fI\-\-max\-unauth\-clients\fR \fBcount\fR]" 4 .IX Item "server-clients-set server [--max-clients count] [--max-unauth-clients count]" Set new client-related limits on \fIserver\fR. .RS 4 .IP "\fI\-\-max\-clients\fR" 4 .IX Item "--max-clients" Change the upper limit of the maximum overall number of clients connected to \&\fIserver\fR to value \fBcount\fR. The value for this limit has to be always greater than the value of \fI\-\-max\-unauth\-clients\fR. .IP "\fI\-\-max\-unauth\-clients\fR" 4 .IX Item "--max-unauth-clients" Change the upper limit of the maximum number of clients waiting for authentication, in order to be connected to \fIserver\fR, to value \fBcount\fR. The value for this limit has to be always lower than the value of \&\fI\-\-max\-clients\fR. .RE .RS 4 .RE .SH "CLIENT COMMANDS" .IX Header "CLIENT COMMANDS" The following commands provide management and monitoring of clients connected to one of daemon's available servers. Clients are specified by their numeric \s-1ID\s0 which is obtained by listing all clients connected to a specified server (see command \fBclient-list\fR). .IP "\fBclient-list\fR \fIserver\fR" 4 .IX Item "client-list server" Print a table showing the list of clients connected to , also providing information about transport type used on client's connection (supported transports include \fBunix\fR, \fBtcp\fR, and \fBtls\fR), as well as providing information about client's connection time (system local time is used). .IP "\fBclient-info\fR \fIserver\fR \fIclient\fR" 4 .IX Item "client-info server client" Retrieve identity information about \fIclient\fR from \fIserver\fR. The attributes returned may vary depending on the connection transport used. Transport-dependent attributes include local client process's pid, uid, user name, and group name, as well as socket address of the remote peer, see \&\fBExamples\fR below. .Sp On the other hand, transport-independent attributes include client's SELinux context (if enabled on the host) and \s-1SASL\s0 username (if \s-1SASL\s0 authentication is enabled within daemon). .Sp \&\fBExamples\fR .Sp .Vb 10 \& # virt\-admin client\-info libvirtd 1 \& id : 1 \& connection_time: 2016\-05\-03 13:27:04+0200 \& transport : unix \& readonly : yes \& unix_user_id : 0 \& unix_user_name : root \& unix_group_id : 0 \& unix_group_name: root \& unix_process_id: 10201 \& \& # virt\-admin client\-info libvirtd 2 \& id : 2 \& connection_time: 2016\-05\-03 13:30:33+0200 \& transport : tcp \& readonly : no \& sock_addr : 127.0.0.1:57060 .Ve .IP "\fBclient-disconnect\fR \fIserver\fR \fIclient\fR" 4 .IX Item "client-disconnect server client" Close a connection originating from \fIclient\fR. The \fIserver\fR argument specifies the name of the server \fIclient\fR is currently connected to. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" The following environment variables can be set to alter the behaviour of \f(CW\*(C`virt\-admin\*(C'\fR .IP "VIRT_ADMIN_DEBUG=<0 to 4>" 4 .IX Item "VIRT_ADMIN_DEBUG=<0 to 4>" Turn on verbose debugging of virt-admin commands. Valid levels are .RS 4 .IP "\(bu" 4 VIRT_ADMIN_DEBUG=0 .Sp \&\s-1DEBUG\s0 \- Messages at \s-1ALL\s0 levels get logged .IP "\(bu" 4 VIRT_ADMIN_DEBUG=1 .Sp \&\s-1INFO\s0 \- Logs messages at levels \s-1INFO, NOTICE, WARNING\s0 and \s-1ERROR\s0 .IP "\(bu" 4 VIRT_ADMIN_DEBUG=2 .Sp \&\s-1NOTICE\s0 \- Logs messages at levels \s-1NOTICE, WARNING\s0 and \s-1ERROR\s0 .IP "\(bu" 4 VIRT_ADMIN_DEBUG=3 .Sp \&\s-1WARNING\s0 \- Logs messages at levels \s-1WARNING\s0 and \s-1ERROR\s0 .IP "\(bu" 4 VIRT_ADMIN_DEBUG=4 .Sp \&\s-1ERROR\s0 \- Messages at only \s-1ERROR\s0 level gets logged. .RE .RS 4 .RE .ie n .IP "VIRT_ADMIN_LOG_FILE=""LOGFILE""" 4 .el .IP "VIRT_ADMIN_LOG_FILE=\f(CWLOGFILE\fR" 4 .IX Item "VIRT_ADMIN_LOG_FILE=LOGFILE" The file to log virt-admin debug messages. .IP "\s-1LIBVIRT_ADMIN_DEFAULT_URI\s0" 4 .IX Item "LIBVIRT_ADMIN_DEFAULT_URI" The daemon whose admin server to connect to by default. Set this to a \s-1URI,\s0 in the same format as accepted by the \fBconnect\fR option. This overrides the default \s-1URI\s0 set in any client config file. .IP "\s-1VIRT_ADMIN_HISTSIZE\s0" 4 .IX Item "VIRT_ADMIN_HISTSIZE" The number of commands to remember in the command history. The default value is 500. .IP "LIBVIRT_DEBUG=LEVEL" 4 .IX Item "LIBVIRT_DEBUG=LEVEL" Turn on verbose debugging of all libvirt \s-1API\s0 calls. Valid levels are .RS 4 .IP "\(bu" 4 LIBVIRT_DEBUG=1 .Sp Messages at level \s-1DEBUG\s0 or above .IP "\(bu" 4 LIBVIRT_DEBUG=2 .Sp Messages at level \s-1INFO\s0 or above .IP "\(bu" 4 LIBVIRT_DEBUG=3 .Sp Messages at level \s-1WARNING\s0 or above .IP "\(bu" 4 LIBVIRT_DEBUG=4 .Sp Messages at level \s-1ERROR\s0 or above .RE .RS 4 .Sp For further information about debugging options consult .RE .SH "BUGS" .IX Header "BUGS" Report any bugs discovered to the libvirt community via the mailing list or bug tracker . Alternatively report bugs to your software distributor / vendor. .SH "AUTHORS" .IX Header "AUTHORS" .Vb 1 \& Please refer to the AUTHORS file distributed with libvirt. \& \& Based on the virsh man page. .Ve .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2015 Red Hat, Inc., and the authors listed in the libvirt \s-1AUTHORS\s0 file. .SH "LICENSE" .IX Header "LICENSE" virt-admin is distributed under the terms of the \s-1GNU LGPL\s0 v2+. This is free software; see the source for copying conditions. There is \s-1NO\s0 warranty; not even for \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE\s0 .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIvirsh\fR\|(1), \fIvirt\-xml\-validate\fR\|(1), \fIvirt\-host\-validate\fR\|(1),