VIRT-ADMIN(1)

📦
version 12.8.0 · 8 versions
, in centos-stream 10

✨ NAME ✨

virt-admin — daemon administration interface

okay so this is VIRT-ADMIN(1), the daemon administration interface, and it's giving Virtualization Support. The virt-admin program is the main administration interface for modifying the libvirt daemon configuration at runtime, changing daemon behaviour, and also for monitoring and managing all clients connected to the daemon. basically the daemon's group chat admin panel, but make it terminal 💅

🎀 SYNOPSIS 🎀

virt-admin [OPTION]... [COMMAND_STRING]

virt-admin [OPTION]... COMMAND [ARG]...

🌸 DESCRIPTION 🌸

The basic structure of most virt-admin usage is:

virt-admin [OPTION]... <command> [ARG]...

Where command is one of the commands listed below. Any command starting with # is treated as a comment and silently ignored, all other unrecognized commands are diagnosed. yes bestie, # is the "not now" button and everything else unexpected gets called out 🙈

The virt-admin program can be used either to run one COMMAND by giving the command and its arguments on the shell command line, or a COMMAND_STRING which is a single shell argument consisting of multiple COMMAND actions and their arguments joined with whitespace and separated by semicolons or newlines between commands, where unquoted backslash-newline pairs are elided. Within COMMAND_STRING, 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, and any word starting with unquoted # begins a comment that ends at newline. If no command is given in the command line, virt-admin will then start a minimal interpreter waiting for your commands, and the quit command will then exit the program.

✨ OPTIONS ✨

The virt-admin program understands the following OPTIONS.

  • -c, --connect URI — Connect to the specified URI, as if by the connect command, instead of the default connection. See NOTES.
  • -d, --debug LEVEL — Enable debug messages at integer LEVEL and above. LEVEL can range from 0 to 4 (default). See the documentation of the VIRT_ADMIN_DEBUG environment variable below for the description of each LEVEL.
  • -h, --help — Ignore all other arguments, and behave as if the help command were given instead.
  • -l, --log FILE — Output logging details to FILE.
  • -q, --quiet — Avoid extra informational messages.
  • -v, --version[=short] — Ignore all other arguments, and prints the version of the libvirt library virt-admin is coming from.
  • -V, --version=long — Ignore all other arguments, and prints the version of the libvirt library virt-admin is coming from.

🧚 NOTES 🧚

The virt-admin supports both the monolithic libvirtd daemon and the modular daemons whichever is in use by your system. The connection URI used with -c/--connect or the connect command is based on the name of the controlled daemon e.g.: virtqemud:///system, libvirtd:///system.

⚠️ Running virt-admin requires root privileges when communicating with the system instance of a daemon (URI ending in /system) due to the communications channels used to talk to the daemon. no cap, that's the actual rule.

🌈 GENERIC COMMANDS 🌈

The following commands are generic.

🫶 help

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.

💖 quit, exit

Syntax:

quit
exit

quit this interactive terminal

⭐ version

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

🦋 cd

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.

🎀 pwd

Syntax:

pwd

Will print the current directory.

🔥 connect

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.

💜 uri

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.

👑 DAEMON COMMANDS 👑

The following commands allow one to monitor the daemon's state as well as directly change its internal configuration.

🍓 server-list

Syntax:

server-list

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

🧚 daemon-log-filters

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 for more fine-grained filters tailored to specific modules; in contrast, to affect the whole directory containing several modules this would become "4:util").

💀 daemon-log-outouts

Syntax:

daemon-log-outputs [--outputs string]

(yes, the heading is spelled daemon-log-outouts and the syntax line says daemon-log-outputs — both exactly as given, bestie 🫶)

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

🧨 daemon-timeout

Syntax:

daemon-timeout [--timeout] NUM

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

🌟 daemon-shutdown

Syntax:

daemon-shutdown [--preserve]

Instruct the daemon to exit gracefully. If the --preserve flag is given, it will save state in the same manner that would be done on a host OS shutdown (privileged daemons) or a login session quit (unprivileged daemons).

🌸 SERVER COMMANDS 🌸

Okay bestie, these ones poke at the daemon's internal server config — and ngl, the server is picked by its name, so keep that in mind the whole way down. 💅

🧵 server-threadpool-info

The syntax, exactly as written:

server-threadpool-info server

This pulls the server's threadpool attributes for you, and here's the whole list of what comes back:

  • minWorkers — the bottom limit on how many active workers there can be
  • maxWorkers — the top limit on how many active workers there can be
  • nWorkers — how many workers the threadpool has right now
  • freeWorkers — how many workers are currently free to take a task
  • prioWorkers — how many priority workers are in the threadpool right now
  • jobQueueDepth — how deep the threadpool's job queue currently is

📖 Background (the lore, iykyk)

So every daemon server has a threadpool, right, and that's what actually gets tasks done for the clients connected to it. When a client request lands on the server, the server checks: is there a worker free to do this task, or should it spin up a new worker for the job? (And not me you knowing that a worker isn't destroyed when it's done — it just goes back to being free.) ✨

But here's the thing — creating new workers only works while the current number of workers is still below the configured upper limit. No sneaking past it, bestie. 🚫

And on top of all those 'standard' workers, a threadpool also holds a special little squad called priority workers. Their whole job is running tasks that — unlike the stuff normal workers handle — are fully within libvirt's control, and libvirt guarantees a task like that cannot hang, so it will always finish. The example they give is destroying a domain:

$ virsh destroy <domain>.

Iconic behaviour, honestly. 💅

🎛️ server-threadpool-set

Syntax:

server-threadpool-set server [--min-workers count] [--max-workers count] [--priority-workers count]

This changes threadpool attributes on a server. Heads up though — only a fraction of the attributes described in server-threadpool-info are supported by the setter. Not all of them made the cut, sorry. 🙈

  • --min-workers — the bottom limit to the number of active workers in a threadpool.
  • --max-workers — the upper limit to the number of active workers in a threadpool. If you use this together with --min-workers, the upper limit value has to be greater than the bottom limit value — otherwise the command errors out. No cap, it will actually refuse. 😭
  • --priority-workers — the current number of active priority workers in a threadpool.

👥 server-clients-info

Syntax:

server-clients-info server

Get the current settings of the limits around how new clients connect. The info breaks down into: the max number of clients connected to the server, the max number of clients waiting for authentication in order to be connected to the server, plus the current runtime values — specifically, how many clients are connected to the server right now and how many clients are waiting for authentication right now.

Example time:

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

Look at those numbers living their best life. 🦋

🔢 server-clients-set

Syntax:

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

Sets shiny new client-related limits on the server.

  • --max-clients — change the upper limit of the maximum overall number of clients connected to the server to the value count. Important: this limit's value has to always be greater than the value of --max-unauth-clients. Periodt. 👑
  • --max-unauth-clients — change the upper limit of the maximum number of clients waiting for authentication (in order to be connected to the server) to the value count. And this one's value has to always be lower than the value of --max-clients. They keep each other in check, it's giving mutual accountability. 🫶

🔐 server-update-tls

Syntax:

server-update-tls server

Updates the TLS context on the server. Fresh context, who dis. ✨

  • server — available servers on a daemon. Currently only supports libvirtd or virtproxyd.

💖 CLIENT COMMANDS 💖

These ones are all about managing and monitoring the clients connected to one of the daemon's available servers. Clients get specified by their numeric ID, which you get by listing all clients connected to a specified server — see client-list below, she's your plug. 🌈

📋 client-list

Syntax:

client-list server

Prints a table showing the list of clients connected to <server>, and it also tells you about the transport type used on the client's connection (supported transports include unix, tcp, and tls), plus info about the client's connection time (system local time is what gets used). A whole little gossip session in table form. ☕

🔍 client-info

Syntax:

client-info server client

Grabs identity info about a client from the server. Fair warning: the attributes that come back may vary depending on the connection transport used. 😮

Transport-dependent attributes include the local client process's pid, uid, user name, and group name, plus the socket address of the remote peer — see the Examples right below.

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

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

✂️ client-disconnect

Syntax:

client-disconnect server client

Closes a connection originating from client. The server argument specifies the name of the server the client is currently connected to. It's not blocking them, it's setting boundaries. 💅

🌿 ENVIRONMENT 🌿

You can set these environment variables to alter how virt-admin behaves, bestie:

  • VIRT_ADMIN_DEBUG=<0 to 4> — turns on verbose debugging of virt-admin commands. Valid levels are:
    • VIRT_ADMIN_DEBUG=0 — DEBUG — messages at ALL levels get logged
    • VIRT_ADMIN_DEBUG=1 — INFO — logs messages at levels INFO, NOTICE, WARNING and ERROR
    • VIRT_ADMIN_DEBUG=2 — NOTICE — logs messages at levels NOTICE, WARNING and ERROR
    • VIRT_ADMIN_DEBUG=3 — WARNING — logs messages at levels WARNING and ERROR
    • VIRT_ADMIN_DEBUG=4 — ERROR — messages at only ERROR level get logged.
  • **VIRT_ADMIN_LOG_FILE=``LOGFILE```** — the file to log virt-admin` debug messages to.
  • LIBVIRT_ADMIN_DEFAULT_URI — the daemon whose admin server to connect to by default. Set this to a URI, in the same format as accepted by the connect option. This overrides the default URI set in any client config file. Main character override energy. 👑
  • VIRT_ADMIN_HISTSIZE — the number of commands to remember in the command history. The default value is 500.
  • LIBVIRT_DEBUG=LEVEL — turns on verbose debugging of all libvirt API calls. Valid levels are:
    • LIBVIRT_DEBUG=1 — messages at level DEBUG or above
    • LIBVIRT_DEBUG=2 — messages at level INFO or above
    • LIBVIRT_DEBUG=3 — messages at level WARNING or above
    • LIBVIRT_DEBUG=4 — messages at level ERROR or above

For further info about debugging options, consult https://libvirt.org/logging.html 🧚

🎀 AUTHORS 🎀

Please refer to the AUTHORS file distributed with libvirt. (They're all in there, go say hi. 🫶)

🐛 BUGS 🐛

Please report all the bugs you discover — and yes, you should. 🙈 This should be done via either:

  1. the mailing list — https://libvirt.org/contact.html
  2. the bug tracker — https://libvirt.org/bugs.html

Alternatively, you may report bugs to your software distributor / vendor.

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

📜 LICENSE 📜

virt-admin is distributed under the terms of the GNU LGPL v2+. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 💀 Like, none. Zero. Nada.

👀 SEE ALSO 👀

virsh(1), virt-xml-validate(1), virt-host-validate(1), https://libvirt.org/

That's the whole page, bestie! 🦋 This one came from the libvirt VIRT-ADMIN(1) man page, dated 2016-05-03 (that's the date on the footer, don't come for me 🫶). Now go forth and administrate — you've got this fr fr. 💖✨🎀

📦 where this page comes from