VIRT-WHO-CONFIG(5)

📦 version 1.32.1, in centos-stream 10, centos-stream 9, fedora 43, fedora 44

💖 NAME 💖

virt-who-config — the configuration for virt-who, bestie ✨

🌸 SYNOPISIS 🌸

/etc/virt-who.conf /etc/virt-who.d/*.conf

🦋 DESCRIPTION 🦋

okay so the config format is ini-like, and it lives in two places: /etc/virt-who.conf and /etc/virt-who.d/*.conf. 💅

The files chillin' in /etc/virt-who.d/*.conf are called virtualization backend configurations. Every non-hidden file in that directory that ends in .conf counts as a configuration file, no cap. And listen — if there's no section in a config file (that's the name in square brackets, bestie), then that file just gets ignored and a warning gets shown. 🙈

The config at /etc/virt-who.conf is the main configuration for virt-who — that's the main character right there. 👑

Down below is the whole rundown of both the required and the optional options for both kinds of configs, and how they actually get used. 🎀

✨ GENERAL CONFIGURATION ✨

The general configuration file (it lives at /etc/virt-who.conf) has three special sections: global, defaults, and system_environment. 💖

The settings you can put in defaults are literally any setting listed in the VIRTUALIZATION BACKEND CONFIGURATION section of this manual, and they get applied as defaults to the configurations found in /etc/virt-who.d/*.conf. so handy.

The settings in global affect the overall operation of the application — the whole vibe check of the app, fr fr. The following are options that can be specified in the global section:

  • interval — how often to check connected hypervisors for changes (in seconds). It also affects how often a mapping is reported. ⏰
  • reporter_id — the id of this virt-who instance, and it gets reported with all the mappings. Defaults to HOSTNAME-MACHINEID. 🪪
  • debug — enable debugging output 🐛
  • oneshot — send the list of guest IDs and exit immediately. bye bestie 👋
  • log_per_config — write a separate log file per configuration in the config directory 📁
  • log_dir — the absolute path of the directory to write logs to 📂
  • log_file — the file name to write logs to (used only if log_per_config=False) 📝
  • configs — a list of files containing configurations for virt-who. Used to specify locations other than the default 🗺️

The settings in system_environment get written to the system's environment and are available for the duration of the process execution. Example options that can be specified in the system_environment section:

  • HTTPS_PROXY — proxy hostname for all https requests 🔒
  • HTTP_PROXY — proxy hostname for all http requests 🌐
  • NO_PROXY — a comma-separated list of hostnames or domains or ip addresses to ignore proxy settings for. Optionally this may be set to '*' to bypass proxy settings for all hostnames domains or ip addresses. 🚫

🌈 VIRTUALIZATION BACKEND CONFIGURATION 🌈

Each section (or group) — denoted by an arbitrary name for the configuration, in square brackets — is read in. 📖

The only required key is type, and it has to be one of the allowed virtualization backend names: ahv, libvirt, esx, hyperv, fake, or kubevirt. periodt. 💅

Please note that special characters must not be escaped. ⚠️

Other options that can be supplied are:

  • server — hostname, IP address or URL of the server that provides virtualization information (not applicable for kubevirt mode). 🖥️
  • username — username for authentication to the server (not applicable for kubevirt mode). May include a domain. Do not escape the backslash between domain and username. 🙅
  • password — password for authentication to the server (not applicable for kubevirt mode). 🔑
  • encrypted_password — alternative to the password option, an encrypted password that is generated by the virt-who-password(8) utility. 🔐
  • owner — owner for use with Subscription Asset Manager, the Red Hat Customer Portal, or Satellite 6 (not applicable for Satellite 5). 👤
  • rhsm_username — optional username to use to communicate with Subscription Asset Manager or Satellite 6 instead of the registered system's identity certificate. (not applicable for Satellite 5) 🎫
  • rhsm_password — optional password to use to communicate with Subscription Asset Manager or Satellite 6 instead of the registered system's identity certificate. (not applicable for Satellite 5) 🎫
  • rhsm_encrypted_password — alternative to the rhsm_password option, an encrypted password that is generated by the virt-who-password(8) utility. 🔐
  • rhsm_hostname — optional hostname of the Subscription Asset Manager or Satellite 6 server, to use in place of the host defined in the system's rhsm.conf. 🏠
  • rhsm_port — optional port for the Subscription Asset Manager or Satellite 6 server, to use in place of the port defined in the system's rhsm.conf. 🚪
  • rhsm_prefix — optional prefix for the Subscription Asset Manager or Satellite 6 server, to use in place of the prefix defined in the system's rhsm.conf. 🏷️
  • rhsm_proxy_hostname — optional proxy host name for the Subscription Asset Manager or Satellite 6 server, to use in place of the proxy host name defined in the system's rhsm.conf. 🌐
  • rhsm_proxy_port — optional proxy port for the Subscription Asset Manager or Satellite 6 server, to use in place of the proxy port defined in the system's rhsm.conf. 🔌
  • rhsm_proxy_user — optional proxy username for the Subscription Asset Manager or Satellite 6 server, to use in place of the proxy username defined in the system's rhsm.conf. 🙋
  • rhsm_proxy_password — optional proxy password for the Subscription Asset Manager or Satellite 6 server, to use in place of the proxy password defined in the system's rhsm.conf. 🤫
  • rhsm_encrypted_proxy_password — alternative to the rhsm_proxy_password option; an encrypted password generated by the virt-who-password(8) utility. 🔐
  • rhsm_no_proxy — optional proxy settings for the Subscription Asset Manager or Satellite 6 server, to use in place of the no proxy filter defined in the system's rhsm.conf. 🚫
  • rhsm_insecure — optional boolean to eliminate the validation of tls certificates during connection to the Subscription Asset Manager or Satellite 6 server, to use in place of the insecure value defined in the system's rhsm.conf. 😬
  • sat_server — hostname, IP address or URL of the Satellite 5 server. 🛰️
  • sat_username — username for authentication to the Satellite 5 server. 🙋
  • sat_password — password for authentication to the Satellite 5 server. 🔑
  • sat_encrypted_password — alternative to the sat_password option, an encrypted password that is generated by the virt-who-password(8) utility. 🔐
  • filter_hosts — only hosts whose uuid (or hostname or hwuuid, based on hypervisor_id) is specified in the comma-separated list in this option will be reported. Wildcards and regular expressions are supported. Put the value into double-quotes if it contains special characters (like comma). filter_host_uuids is a deprecated alias for this option. 🧲
  • exclude_hosts — hosts whose uuid (or hostname or hwuuid, based on hypervisor_id) is specified in the comma-separated list in this option will NOT be reported. Wildcards and regular expressions are supported. Put the value into double-quotes if it contains special characters (like comma). exclude_host_uuids is a deprecated alias for this option. 🙅
  • filter_type — when this property is not set, then virt-who tries to detect wildcards or a regular expression in the value of filter_hosts or exclude_hosts. This option allows you to specify usage of a regular expression (value 'regex') or wildcards (value 'wildcards'). 🔍
  • hypervisor_id — the property that should be used as identification of the hypervisor. Can be one of the following: uuid, hostname, hwuuid. Note that some virtualization backends don't have all of them implemented. Default is uuid. hwuuid is applicable to esx only. This property is meant to be set up before the initial run of virt-who. Changing it later will result in duplicated entries in the subscription manager. 🪪
  • #kubeconfig — path to Kubernetes configuration file which contains authentication and connection details. Used by the kubevirt option. ☸️
  • #kubeversion — API version used to override the kubevirt api version fetched from the cluster. Used by the kubevirt option. ☸️
  • #insecure — eliminate validation of tls certificates during connection to kubevirt. 😬

🎀 EXAMPLE 🎀

[test-esx]
type=esx
server=1.2.3.4
username=admin
password=password
owner=test
rhsm_username=admin
rhsm_password=password

💅 BACKEND SPECIFIC OPTIONS 💅

So like, every backend has its own lil special sauce. Here's the tea, per backend. 🫖

✨ ESX BACKEND ✨

  • filter_host_parents — only the hosts whose cluster ID shows up in this comma-separated list get reported, everyone else is on read. If the name has special characters in it (commas, we're looking at you bestie 😭), wrap it in double-quotes. Wanna find those cluster IDs in VMware? Run this PowerCLI command: Get-Cluster “ClusterName” | Select ID
  • exclude_host_parents — the inverse vibe: hosts whose cluster ID is in this comma-separated list will NOT be reported. Same deal with special characters, put the name in double-quotes if it's got any. And same PowerCLI command to hunt down the domain names in VMware: Get-Cluster “ClusterName” | Select ID
  • simplified_vim — by default virt-who uses a stripped-down version of the vimService.wsdl file that holds the vSphere SOAP API definition. Set this option to false and it'll use the server-provided wsdl file instead, which gets retrieved automatically. slay, automatic. ✨

🌸 NUTANIX BACKEND 🌸

  • prism_central — set literally any value here and the application switches over to Version 3 communication with the AHV API. That's it, that's the whole option. iconic, honestly. 💖

🦋 KUBEVIRT BACKEND 🦋

Okay so the Kubevirt backend runs off a Kubernetes configuration file — that file is where the cluster connection details and an authentication token live. You do not need to hand it a hostname or user credentials. Periodt. 🙅‍♀️

But bestie, before you use that kubeconfig file, please make sure you're logged into the cluster so the token actually gets written into the file. To log in you run:

oc login --username=myuser --password=mypass

🎀 FAKE BACKEND 🎀

The fake backend pulls host/guests associations straight off a file on disk. Like so:

[fake-virt]
type=fake
file=/path/to/json
is_hypervisor=True
  • type — has to be fake always. No negotiation. 💀
  • is_hypervisor — if true (which is the default), this option means the fake data gets fetched from a multihost environment. 👑
  • file — the absolute path to the JSON file, and it's gotta have the same structure as the file that comes back from the virt-who --print command. Example time:
{
    "hypervisors": [
        {
            "uuid": "7e98b6ea-0af1-4afa-b846-919549bb0fe2",
            "guests": [
                {
                    "guestId": "8ae19f08-2605-b476-d42e-4bd5a39f466c",
                    "state": 1
                },
                ...
            ]
        },
        ...
    ]
}

🔄 CONFIGURATION MIGRATION 🔄

So back in the day, previous versions of virt-who had extra ways to do config, and now we're cleaning house:

  • Setting of environment variables [set in the user's profile script or in the default global profile]
  • A service environment file [/etc/sysconfig/virt-who]

The new version of virt-who no longer supports setting most options via the environment. Rude? Maybe. Necessary? Yes. 😌

But because nobody wants to lose a config that was working perfectly fine, a migration script got added. That script takes the known system environment variables [VIRTWHO_INTERVAL, VIRTWHO_DEBUG, VIRTWHO_ONESHOT] plus the entries in the service environment file, and folds them all into the general configuration file. The known variables land in the global section, while anything else in the service environment file [i.e. HTTPS_PROXY] lands in the system_environment section. Heads up: this migration can totally result in multiple entries for one specific field. it's giving duplicates, but make it intentional. 🙈

Every new entry in the general configuration file shows up after a comment saying it was migrated, so you always know what came from where. The service environment file gets deleted after its entries are migrated — but the known system environment variables need to be manually removed by you, or they'll get migrated again if the script is rerun. And nope, those variables won't be recognized by virt-who even if they stick around. delete them, bestie, I'm begging. 😭

The migration script runs automatically when a new RPM is installed, but you can also run it manually with python after the RPM is installed:

[python_sitelib]/virtwho/migrate/migrateconfiguration.py

👑 AUTHOR 👑

  • Radek Novacek <rnovacek at redhat dot com>
  • William Poteat <wpoteat at redhat dot com>

💜 SEE ALSO 💜

and that's the whole page, bestie!! 🎉 This one's from the virt-who crew, dated October 2015, and it lives at VIRT-WHO-CONFIG(5) — go forth and configure responsibly, you absolute icon 💅✨🫶

📦 where this page comes from