virt-admin - Man Page

Syntax:

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.

To display detailed information for a specific command, use its name as the option.

Syntax:

quit
exit

quit this interactive terminal

Syntax:

version

will print out the version info about which libvirt library was this client built from. As opposed to virsh client, the output already includes the version of the daemon.

Example:

$ virt-admin version
Compiled against library: libvirt 1.2.21
Using library: libvirt 1.2.21
Running against daemon: 1.2.20

Syntax:

cd [directory]

Will change current directory to directory.  The default directory for the cd command is the home directory or, if there is no HOME variable in the environment, the root directory.

This command is only available in interactive mode.

Syntax:

pwd

Will print the current directory.

Syntax:

connect [URI]

(Re)-Connect to a daemon's administrating server. The URI parameter specifies how to connect to the administrating server. If LIBVIRT_ADMIN_DEFAULT_URI or uri_default (see below) were set, connect 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.

See Notes on picking the correct URI corresponding to a libvirt daemon.

To find the currently used URI, check the uri command documented below.

Syntax:

uri

Prints the administrating server canonical URI, can be useful in shell mode. If no uri was specified, neither LIBVIRT_ADMIN_DEFAULT_URI environment variable nor uri_default option (libvirt-admin.conf) were set, libvirtd:///system is used.

Syntax:

server-list

Lists all manageable servers contained within the daemon the client is currently connected to.

Syntax:

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.

• --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 /etc/libvirt/libvirtd.conf (section 'Logging filters').

Example:

To define a filter which suppresses all e.g. 'virObjectUnref' DEBUG messages, use the following:

$ virt-admin daemon-log-filters "4:util.object"

(Note the '.' 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"):

Syntax:

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.

• --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 /etc/libvirt/libvirtd.conf (section 'Logging outputs').

Example:

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:<absolute_path_to_the_file>"

To define multiple outputs at once they need to be delimited by spaces:

$ virt-admin daemon-log-outputs "4:stderr 2:syslog:<msg_ident>"

Syntax:

daemon-timeout [--timeout] NUM

Sets the daemon timeout to the value of '--timeout' argument. Use --timeout 0 to disable auto-shutdown of the daemon.

Syntax:

server-threadpool-info server

Retrieve server's threadpool attributes. These attributes include:

• minWorkers as the bottom limit to the number of active workers,
• maxWorkers as the top limit to the number of active workers,
• nWorkers as the current number of workers in the threadpool,
• freeWorkers as the current number of workers available for a task,
• prioWorkers as the current number of priority workers in the threadpool, and
• jobQueueDepth as the current depth of threadpool's job queue.

Background

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. In addition to these 'standard' workers, a threadpool also contains a special set of workers called priority 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 <domain>.

Syntax:

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 server-threadpool-info is supported for the setter.

• --min-workers

  The bottom limit to number of active workers in a threadpool.

• --max-workers

  The upper limit to number of active workers in a threadpool. If used in combination with option --min-workers, the value for the upper limit has to be greater than the value for the bottom limit, otherwise the command results in an error.

• --priority-workers

  The current number of active priority workers in a threadpool.

Syntax:

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 server, 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 server and the current number of clients waiting for authentication.

Example:

# virt-admin server-clients-info libvirtd
nclients_max        : 120
nclients            : 3
nclients_unauth_max : 20
nclients_unauth     : 0

Syntax:

server-clients-set server [--max-clients count] [--max-unauth-clients count]

Set new client-related limits on server.

• --max-clients

  Change the upper limit of the maximum overall number of clients connected to server to value count. The value for this limit has to be always greater than the value of --max-unauth-clients.

• --max-unauth-clients

  Change the upper limit of the maximum number of clients waiting for authentication, in order to be connected to server, to value count. The value for this limit has to be always lower than the value of --max-clients.

Syntax:

server-update-tls server

Update tls context on server.

• server

  Available servers on a daemon. Currently only supports 'libvirtd' or 'virtproxyd'.

Syntax:

client-list server

Print a table showing the list of clients connected to <server>, also providing information about transport type used on client's connection (supported transports include unix, tcp, and tls), as well as providing information about client's connection time (system local time is used).

Syntax:

client-info server client

Retrieve identity information about client from server. 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 Examples below.

On the other hand, transport-independent attributes include client's SELinux context (if enabled on the host) and SASL username (if SASL authentication is enabled within daemon).

Examples:

# 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

Syntax:

client-disconnect server client

Close a connection originating from client. The server argument specifies the name of the server client is currently connected to.