virt-who-config.5

.TH VIRT-WHO-CONFIG "5" "October 2015" "virt-who"
.SH NAME
virt-who-config - configuration for virt-who
.SH SYNOPISIS
/etc/virt-who.conf
/etc/virt-who.d/*.conf
.SH DESCRIPTION
Configuration format is ini-like for files /etc/virt-who.conf and /etc/virt-who.d/*.conf.
The configuration files located at /etc/virt-who.d/*.conf are called virtualization backend configurations.
All non-hidden files in this directory (ending in '.conf') are considered configuration files. If no section (name in square brackets) is present in the configuration file, it will be ignored and warning will be shown.
The configuration located at /etc/virt-who.conf is the main configuration for virt-who.
Below are descriptions of both the required and optional options for both kinds of configs and how they are used.
.SH GENERAL CONFIGURATION
The general configuration file (located at /etc/virt-who.conf), has three special sections \fBglobal\fR, \fBdefaults\fR, and \fBsystem_environment\fR.
The settings that can be specified in \fBdefaults\fR are any setting listed in the \fBVIRTUALIZATION BACKEND CONFIGURATION\fR section of this manual. These settings are applied as defaults to the configurations found in /etc/virt-who.d/*.conf.

The settings in the \fBglobal\fR affect the overall operation of the application.
The following are options that can be specified in the \fBglobal\fR section:
.TP
\fBinterval\fR
how often to check connected hypervisors for changes (seconds). Also affects how often a mapping is reported.
.TP
\fBreporter_id\fR
The id of this virt-who instance, reported with all mappings.
Defaults to HOSTNAME-MACHINEID
.TP
\fBdebug\fR
Enable debugging output
.TP
\fBoneshot\fR
Send the list of guest IDs and exit immediately
.TP
\fBlog_per_config\fR
Write a separate log file per configuration in the config directory
.TP
\fBlog_dir\fR
The absolute path of the directory to write logs to.
.TP
\fBlog_file\fR
The file name to write logs to (used only if log_per_config=False)
.TP
\fBconfigs\fR
A list of files containing configurations for virt-who
Used to specify locations other than default

The settings in the \fBsystem_environment\fR are written to the system's environment and are available for the duration of the process execution.
Example options that can be specified in the \fBsystem_environment\fR section:
.TP
\fBHTTPS_PROXY\fR
Proxy hostname for all https requests
.TP
\fBHTTP_PROXY\fR
Proxy hostname for all http requests
.TP
\fBNO_PROXY\fR
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.

.SH VIRTUALIZATION BACKEND CONFIGURATION
Each section (or group), denoted by an arbitrary name for the configuration (in square brackets), is read in

Only required key is \fBtype\fR that has to have one of the allowed virtualization backend names: ahv, libvirt, esx, hyperv, fake, or kubevirt.

Please note that special characters must not be escaped.

Other options that can be supplied are:
.TP
\fBserver\fR
Hostname, IP address or URL of the server that provides virtualization information (not applicable for kubevirt mode).
.TP
\fBusername\fR
Username for authentication to the server (not applicable for kubevirt mode). May include domain. Do not escape the backslash between domain and username.
.TP
\fBpassword\fR
Password for authentication to the server (not applicable for kubevirt mode).
.TP
\fBencrypted_password\fR
Alternative to the password option, encrypted password that is generated by virt-who-password(8) utility.
.TP
\fBowner\fR
Owner for use with Subscription Asset Manager, the Red Hat Customer Portal, or Satellite 6 (not applicable for Satellite 5)
.TP
\fBrhsm_username\fR
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)
.TP
\fBrhsm_password\fR
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)
.TP
\fBrhsm_encrypted_password\fR
Alternative to the rhsm_password option, encrypted password that is generated by virt-who-password(8) utility.
.TP
\fBrhsm_hostname\fR
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.
.TP
\fBrhsm_port\fR
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.
.TP
\fBrhsm_prefix\fR
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.
.TP
\fBrhsm_proxy_hostname\fR
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.
.TP
\fBrhsm_proxy_port\fR
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.
.TP
\fBrhsm_proxy_user\fR
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.
.TP
\fBrhsm_proxy_password\fR
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.
.TP
\fBrhsm_encrypted_proxy_password\fR
Alternative to the rhsm_proxy_password option; encrypted password generated by the virt-who-password(8) utility.
.TP
\fBrhsm_no_proxy\fR
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.
.TP
\fBrhsm_insecure\fR
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 insecure value defined in the system's rhsm.conf.
.TP
\fBsat_server\fR
Hostname, IP address or URL of the Satellite 5 server.
.TP
\fBsat_username\fR
Username for authentication to the Satellite 5 server.
.TP
\fBsat_password\fR
Password for authentication to the Satellite 5 server.
.TP
\fBsat_encrypted_password\fR
Alternative to sat_password option, encrypted password that is generated by virt-who-password(8) utility.
.TP
\fBfilter_hosts\fR
Only hosts which uuid (or hostname or hwuuid, based on \fBhypervisor_id\fR) is specified in comma-separated list in this option will be reported. Wildcards and regular expressions are supported.  Put the value into the double-quotes if it contains special characters (like comma). \fBfilter_host_uuids\fR is deprecated alias for this option.
.TP
\fBexclude_hosts\fR
Hosts which uuid (or hostname or hwuuid, based on \fBhypervisor_id\fR) is specified in comma-separated list in this option will \fBNOT\fR be reported.  Wildcards and regular expressions are supported.  Put the value into the double-quotes if it contains special characters (like comma). \fBexclude_host_uuids\fR is deprecated alias for this option.
.TP
\fBfilter_type\fR
When this property is not set, then virt-who tries to detect wildcards or regular expression in value of filter_hosts or exclude_hosts. This option allows to specify usage of regular expression (value 'regex') or wildcards (value 'wildcards').
.TP
\fBhypervisor_id\fR
Property that should be used as identification of the hypervisor. Can be one of following: \fBuuid\fR, \fBhostname\fR, \fBhwuuid\fR. Note that some virtualization backends don't have all of them implemented. Default is \fBuuid\fR. \fBhwuuid\fR is applicable to esx only. This property is meant to be set up before initial run of virt-who. Changing it later will result in duplicated entries in the subscription manager.
.TP
\fB#kubeconfig\fR
Path to Kubernetes configuration file which contains authentication and connection details. Used by kubevirt option
.TP
\fB#kubeversion\fR
API version used to override kubevirt api version fetched from the cluster. Used by kubevirt option
.TP
\fB#insecure\fR
Eliminate validation of tls certificates during connection to kubevirt

.SH EXAMPLE
[test-esx]
.br
type=esx
.br
server=1.2.3.4
.br
username=admin
.br
password=password
.br
owner=test
.br
rhsm_username=admin
.br
rhsm_password=password

.SH BACKEND SPECIFIC OPTIONS

.SS ESX BACKEND

.TP
\fBfilter_host_parents\fR
Only hosts which cluster ID is specified in comma-separated list in this option will be reported. Put the name into the double-quotes if it contains special characters (like comma). PowerCLI command to find the domain names in VMware `Get-Cluster “ClusterName” | Select ID`
.TP
\fBexclude_host_parents\fR
Exclude hosts which cluster ID is specified in comma-separated list in this option will \fBNOT\fR be reported. Put the name into the double-quotes if it contains special characters (like comma). PowerCLI command to find the domain names in VMware `Get-Cluster “ClusterName” | Select ID`
.TP
\fBsimplified_vim\fR
virt-who by default uses stripped-down version of vimService.wsdl file that contains vSphere SOAP API definition. Set this option to \fBfalse\fR to use server provided wsdl file that will be retrieved automatically.

.SS NUTANIX BACKEND

.TP
\fBprism_central\fR
Any value set for this parameter will cause the application to use Version 3 communication with the AHV API

.SS KUBEVIRT BACKEND

Kubevirt backend uses a Kubernetes configuration file where there are cluster connection details and an authentication token. There is no need to provide a hostname nor user credentials.
Before using the kubeconfig file please make sure to login to the cluster so the token is written to the file. To login you need to run:

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

.SS FAKE BACKEND

Fake backend reads host/guests associations from the file on disk, for example:

[fake-virt]
.br
type=fake
.br
file=/path/to/json
.br
is_hypervisor=True
.br

.TP
\fBtype\fR
Must be always \fBfake\fR.

.TP
\fBis_hypervisor\fR
If \fbtrue\fR (default), the option determines that the fake data are fetched from multihost environment.

.TP
\fBfile\fR
Absolute path to the JSON file that has the same structure as file returned from \fBvirt-who --print\fR command, for example:
.br
{
    "hypervisors": [
.br
        {
.br
            "uuid": "7e98b6ea-0af1-4afa-b846-919549bb0fe2",
.br
            "guests": [
.br
                {
.br
                    "guestId": "8ae19f08-2605-b476-d42e-4bd5a39f466c",
.br
                    "state": 1
.br
                },
.br
                ...
.br
            ]
.br
        },
.br
        ...
.br
    ]
.br
}

.SH CONFIGURATION MIGRATION

Previous versions of virt-who employed additional means of configuration:

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

The new version of virt-who no longer supports setting most options via the environment. In order to not lose previously valid configurations that made use of environment variables,
a migration script has been added. That script will incorporate the known system environment variables [VIRTWHO_INTERVAL, VIRTWHO_DEBUG, VIRTWHO_ONESHOT] and the entries in the
service environment file into the general configuration file. The known variables will land in the \fBglobal\fR section while any others in the service environment file [i.e. HTTPS_PROXY]
will land in the \fBsystem_environment\fR section. This migration may result in multiple entries for a specific field.

Each new entry in the general configuration file will come after a comment indicating that it was migrated. The service environment file will be deleted after its entries are
migrated, but the known system environment variables will need to be manually removed or they will be migrated again if the script is rerun. Those variables will not be recognized
by virt-who even if they remain.

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

[python_sitelib]/virtwho/migrate/migrateconfiguration.py


.SH AUTHOR
Radek Novacek <rnovacek at redhat dot com>
.br
William Poteat <wpoteat at redhat dot com>

.SH SEE ALSO
virt-who(8), virt-who-password(8)