VIRT-WHO(8)

VIRT-WHO 💖

okay bestie, gather round, because we're talking about virt-who — and yes this is section 8 of the System Manager's Manual, she's official, she's got a manual page and everything 👑

NAME: virt-who — the agent that reports virtual guest IDs to an entitlement server. That's the whole job. She snitches (affectionately) about your guests, on purpose, to a server that wants to know.

---

✨ SYNOPSIS ✨

virt-who [-d] [-i INTERVAL] [-o] [-s]

literally the whole vibe in one line, no cap.

---

🎀 OPTIONS 🎀

• -h, --help — show this help message and exit. she's helpful like that 🫶
• -d, --debug — enable debugging output. turn this on when you want her to overshare.
• -o, --one-shot — send the list of guest IDs and exit immediately. one and done, hit it and quit it, no lingering 💅
• -i INTERVAL, --interval=INTERVAL — acquire and send guest information each N seconds. but listen: this option is a recommendation only. the requested interval might not be honoured, and the actual interval might end up longer or shorter depending on which backend is being used. it's giving "suggestion box, not a contract" 😭
• -p, --print — print the host/guests association in JSON format to standard output. no server involved, just vibes and json ✨
• -c, --config — use a configuration file directly. this will override configuration from other files. heads up: the 'global', 'default', and 'system_environment' sections are not read from files passed in via this option — those are only read from /etc/virt-who.conf. can be used multiple times. see virt-who-config(5) for the deets on the config file format 📄
• -s, --status — confirm the correctness of the configurations. tests the connections and builds a report on the result. the default display is a short summary of the configurations. it's a whole vibe check for your setup 🔍
• -j, --json — used with status to return a more detailed report in json format. pair her with -s for the full data dump 🍓

---

🌸 USAGE 🌸

MODE

virt-who has four modes she can run in. four. count them. she's versatile 👑

1. one-shot mode

# virt-who -o

in this mode virt-who just sends the host to guest association to the server once and then exits. blink and she's gone 💨

2. interval mode

# virt-who -i INTERVAL

this is the default mode, bestie. virt-who will listen to change events (if available) or do a polling with the given interval, and will send the host to guest association when it changes. the default polling interval is 3600 seconds and can be changed using -i INTERVAL (in seconds). she'll just be there. watching. periodically. 🦋

3. print mode

# virt-who -p

this mode is similar to oneshot mode, except the host to guest association is not sent to the server — it's printed to standard output instead. same energy, different destination, iykyk 💖

3. status mode

# virt-who -s

(yes both of these are numbered 3, we don't know either, it's iconic in its own way 🙈)

this mode is for configuration diagnosis. the host to guest association is not compiled and is not sent to the server. when executed, it will confirm the ability to log into and retrieve data from the source for each configuration. it will also confirm the credentials and organization for each destination in the configurations. it produces results in two ways that you can use to diagnose problems.

the first is a summary:

Configuration Name: esx_config1
Source Status: success
Destination Status: success

Configuration Name: hyperv-55
Source Status: failure
Destination Status: failure

the second is a machine-readable json output (which is generated when the -j/--json option is used):

{
    "configurations": [
        {
            "name":"esx-conf1",
            "source":{
                "connection":"esx_system.example.com",
                "status":"success",
                "last_successful_retrieve":"2020-02-28 07:25:25
UTC",
                "hypervisors":20,
                "guests":37
            },
            "destination":{
                "connection":"candlepin.example.com",
                "status":"success",
                "last_successful_send":"2020-02-28 07:25:27 UTC",
                "last_successful_send_job_status":"FINISHED"
            }
        },
        {
            "name":"hyperv-55",
            "source":{
                "connection":"windows10-3.company.com",
                "status":"failure",
                "message":"Unable to connect to server: invalid
credentials",
                "last_successful_retrieve":"none"
            },
            "destination":{
                "connection":"candlepin.company.com",
                "status":"failure",
                "message":"ConnectionRefusedError: [Errno 111]
Connection refused",
                "last_successful_send":"none",
                "last_successful_send_job_status":"none"
            }
        }
    ] }

---

💜 LOGGING 💜

virt-who always writes error output to the file /var/log/rhsm/rhsm.log. she also writes that same output to standard error output when she's started from the command line. so like, she tells you AND she tells the file. receipts everywhere 🧾

virt-who can be started with the option -d in all modes and with all backends. this option enables verbose output with more information. more words, more clues, more chaos ✨

---

🔥 SECURITY 🔥

okay this part is serious, stay with me.

virt-who may present security concerns in some scenarios because she needs access to every hypervisor in the environment. that's a lot of access, bestie, that's main character energy with root-level trust.

to minimize security risk: virt-who is a network client, not a server. she only does outbound connections to find and register new hypervisors, and she does not need access to any virtual machines. periodt.

to further reduce risk: deploy virt-who in a small virtual machine with a minimal installation, and lock it down from any unsolicited inbound network connections. tiny box, big boundaries 💅

here's a list of ports that need to be open for different hypervisors:

• VMWare ESX/vCenter: 443/tcp
• Hyper-V: 5985/tcp
• RHEV-M: 443/tcp or 8443/tcp (depending on version)
• libvirt: depending on transport type, default (for remote connections) is qemu over ssh on port 22
• local libvirt uses a local connection and doesn't need an open port
• kubevirt: 8443/tcp
• Nutanix AHV: 9440/tcp

virt-who also needs to have access to an entitlement server. default port is 443/tcp. all the ports might be changed by system administrators, so don't come for me if your setup looks different 🌈

using the same network for the machine running virt-who as for hypervisor management software, instead of production VM networks, is suggested. keep her in the management lane, not the party lane 🎀

ngl, "she needs access to every hypervisor" is the kind of sentence that should come with a seatbelt. read it twice.

---

👑 AUTHORS 👑

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

---

and that's the whole page, bestie 🦋💖 this was virt-who, manual page VIRT-WHO(8), from the System Manager's Manual, dated April 2016. she's been serving looks and guest IDs for a minute and she's not stopping. slay, log off, touch grass, and remember: outbound connections only 💅✨🌸