VHOSTMD(8)

📦

version 1.2 · 2 versions

1.2 · fedora 44, opensuse-leap 16.0 (latest)
1.1 · fedora 43

🦋 VHOSTMD 🦋 — the metrics gathering daemon (section 8, System Manager's Manual, bestie)

okay so listen. this is vhostmd, and it's genuinely one of my faves. it's a little daemon that writes host metrics to a disk so your VMs can peek at them. no cap, it's iconic.

🌸 NAME 🌸

vhostmd — a metrics gathering daemon. that's the whole vibe. she gathers metrics. she's a daemon. 💅

✨ SYNOPSIS ✨

vhostmd [ OPTION ]

just the one binary, bestie. she takes options. that's it. periodt.

💖 DESCRIPTION 💖

vhostmd provides a "metrics communication channel" between a host and its hosted virtual machines, which lets the VMs do a limited introspection of host resource usage from inside themselves. 🫶

so like, why do you care? in hosting environments this is lowkey a big deal: it gives VM administrators a limited view of host resource consumption, which can potentially explain a performance degradation happening inside the virtual machine. so instead of everyone being confused and mad, you get data. slay.

vhostmd will periodically write metrics to a disk. the metrics to write, how often to write them, and where to write them are all adjustable via the /etc/vhostmd/vhostmd.conf configuration file. then that disk can be surfaced read-only to virtual machines using tools provided by the host's virtualization platform. that's the whole trick. it's giving genius honestly.

👑 OPTIONS 👑

-h, --help — displays help and then exits. she said bye 👋
-v, --verbose — verbose messages. she gets chatty. we love that for her.
-d, --no-daemonize — the process will not daemonize. she stays in the foreground, main character energy.
-c, --connect <uri> — sets the libvirt URI. if you leave it unspecified, we connect to the default libvirt hypervisor. > ⚠️ it is recommended that you specify this, because libvirt's method for choosing the default hypervisor can give unexpected results. don't be lazy, bestie, type the URI.
-u, --user <user> — drops root privileges and runs as the named non-root user. safety first, always. 🧚
-p, --pid-file <file> — specify an alternate path for vhostmd to record its process-id in. normally it's /var/run/vhostmd.pid.
-f, --config <file> — specify a different configuration file. normally /etc/vhostmd/vhostmd.conf.

🎀 CONFIG FILE 🎀

at startup, vhostmd reads /etc/vhostmd/vhostmd.conf, if it exists. (see the -f option if you wanna point somewhere else. you're allowed.)

the default configuration file (listed below) defines a 256Kbyte metrics disk in /dev/shm/vhostmd0, updated every 5 seconds. it also includes a few examples of user-defined metrics, which provide a (currently simplistic) mechanism for extending the metrics gathered by vhostmd.

<vhostmd>
  <globals>
    <disk>
      <name>host-metrics-disk</name>
      <path>/dev/shm/vhostmd0</path>
      <size unit="k">256</size>
    </disk>
    <update_period>5</update_period>
    <path>/usr/bin:/usr/sbin:/usr/share/vhostmd/scripts</path>
  </globals>
  <metrics>
    <metric type="string" context="host">
      <name>HostName</name>
      <action>virsh hostname | tr -d '[:space:]'</action>
    </metric>
    <metric type="string" context="host">
      <name>VirtualizationVendor</name>
      <action>/bin/rpm -q --info xen | grep Vendor: |
               awk '{print substr($0, index($0,$5)) }'</action>
    </metric>
    <metric type="uint32" context="host">
      <name>TotalPhyCPUs</name>
      <action>xm info | gawk '/^nr_cpus/ {print $3}'</action>
    </metric>
    <metric type="uint32" context="host">
      <name>NumCPUs</name>
      <action>xm info | gawk '/^nr_cpus/ {print $3}'</action>
    </metric>
    <metric type="uint64" context="host">
      <name>TotalPhyMem</name>
      <action>xm info | gawk '/^total_memory/ {print $3}'</action>
    </metric>
    <metric type="uint64" context="host">
      <name>UsedMem</name>
      <action>xentop -b -i 1 | gawk '/Domain-0/ {print $5}'</action>
    </metric>
    <metric type="uint64" context="host">
      <name>FreeMem</name>
      <action>xm info | gawk '/^max_free_memory/ {print $3}'</action>
    </metric>
    <metric type="uint64" context="host">
      <name>PagedInMemory</name>
      <action>vmstat -s | gawk '/pages paged in/ {print $1}'</action>
    </metric>
    <metric type="uint64" context="host">
      <name>PagedOutMemory</name>
      <action>vmstat -s | gawk '/pages paged out/ {print $1}'</action>
    </metric>
    <metric type="group" context="host">
      <name>PageRates</name>
      <action>pagerate.pl</action>
      <variable name="PageInRate" type="uint64"/>
      <variable name="PageFaultRate" type="uint64"/>
    </metric>
    <metric type="real64" context="host">
      <name>TotalCPUTime</name>
      <action>virsh dominfo 0 | sed 's/: */:/' |
               gawk -F: '/CPU time/ {print $2;}'</action>
    </metric>
    <metric type="real64" context="vm">
      <name>TotalCPUTime</name>
      <action>virsh dominfo NAME | sed 's/: */:/' |
               gawk -F: '/CPU time/ {print $2;}'</action>
    </metric>
    <metric type="xml" context="vm">
      <name>my-metric</name>
      <action>xml-metrics-test.sh</action>
    </metric>
  </metrics>
</vhostmd>

a valid configuration file must contain the root element <vhostmd>. the <globals> element contains configuration global to vhostmd, such as the metrics disk path and the metrics refresh interval. the <metrics> element is a container for all of the <metric> elements. a metric element is used to define a metric, giving it a name and an action that produces the metric value. 🍓

the supplied vhostmd configuration file provides a useful set of default metrics to be collected. you can extend or modify it by editing /etc/vhostmd/vhostmd.conf and changing existing metric definitions or adding new metric definitions under the metrics container. go off, customize.

defined metrics begin with the <metric> element, which contains three attributes: type, context, and unit. ✨

the type attribute describes the metric's value type. supported types are int32, uint32, int64, uint64, real32, real64, string, group, and xml. group is used when an action returns more than one metric value. xml is the most flexible type and specifies that the metric's action returns valid metric XML.
the context attribute indicates whether this is a host or vm metric. supported contexts are host and vm.
the optional unit attribute describes the unit of measure produced for the metric by the defined action.

currently, the metric element contains 3 elements: name, action, and variable. the name element defines the metric's name. the action element describes a command or pipeline of commands used to gather the metric. 💅

any <action> element can contain the magic token CONNECT which is replaced with the string "--connect 'uri'" where uri is the libvirt connection URI (specified on the command line to vhostmd as the -c option). if it wasn't specified, then the token CONNECT is substituted with the empty string. this lets you write virsh commands like this:

virsh -r CONNECT command ...

for metrics of vm context, the tokens NAME, VMID, and UUID may be used where these attributes of a VM are normally provided in a command. when the metric is sampled, these tokens will be substituted with the actual name, ID, or UUID of the vm currently being sampled by vhostmd. it's giving personalization, fr fr.

if the metric type is xml, action is expected to return valid metric XML as defined below in "XML Format of Content".

🌈 Metrics Disk Format 🌈

currently, the disk format is quite simple: a raw, file-backed disk containing a header, immediately followed by metric content.

the header contains the following, all in network-byte order:

4 byte signature, 'mvbd'
4 byte busy flag
4 byte content checksum
4 byte content length

the busy flag permits simple reader/writer synchronization. you can check the busy flag for clear, read the content into a buffer, and check the busy flag again for clear to make sure the content is stable. cute little handshake, honestly. 🤝

🌸 XML Format of Content 🌸

the content is an XML document containing default and user-defined metrics. the format is quite similar to the metrics definitions found in the vhostmd configuration file. a notable addition, as illustrated below, is the value element containing the metric's current value.

<metrics>
  <metric type='real64' context='host'>
    <name>TotalCPUTime</name>
    <value>846.600000</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>PageInRate</name>
    <value>0.000000</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>PageFaultRate</name>
    <value>0.000000</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>PagedOutMemory</name>
    <value>6885044</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>PagedInMemory</name>
    <value>2367980</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>FreeMem</name>
    <value>829</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>UsedMem</name>
    <value>1369088</value>
  </metric>
  <metric type='uint64' context='host'>
    <name>TotalPhyMem</name>
    <value>1919</value>
  </metric>
  <metric type='uint32' context='host'>
    <name>NumCPUs</name>
    <value>2</value>
  </metric>
  <metric type='uint32' context='host'>
    <name>TotalPhyCPUs</name>
    <value>2</value>
  </metric>
  <metric type='string' context='host'>
    <name>VirtualizationVendor</name>
    <value>SUSE LINUX Products GmbH</value>
  </metric>
  <metric type='string' context='host'>
    <name>HostName</name>
    <value>laptop</value>
  </metric>
  <metric type='real64' context='vm' id='0'
       uuid='00000000-0000-0000-0000-000000000000'>
    <name>TotalCPUTime</name>
    <value>847.700000</value>
  </metric>
  <metric type='real64' context='vm' id='2'
       uuid='6be3fdb8-bef5-6fec-b1b7-e61bbceab708'>
    <name>TotalCPUTime</name>
    <value>69.400000</value>
  </metric>
</metrics>

🗂️ FILES 🗂️

/etc/vhostmd/vhostmd.conf
/etc/vhostmd/vhostmd.dtd
/etc/vhostmd/metric.dtd
/var/run/vhostmd.pid

🔍 SEE ALSO 🔍

okay so bestie… this section is literally empty in the original. no cross-references listed, nothing. we're not inventing any, because we don't make stuff up around here. so: nothing here. moving on. 💀

🫶 AUTHORS 🫶

Pat Campbell <plc@novell.com>.
Jim Fehlig <jfehlig@novell.com>.

and that's the whole page, bestie! 💖 this one came from the System Manager's Manual, section 8, and the footer just reads VHOSTMD(8) — no date line, no version stamp, nothing extra. so go forth, write your metrics to a disk, surface it read-only, and let your VMs finally understand why they're slow. you ate. 👑✨🎀

📦 where this page comes from

fedora 44: vhostmd 1.2-1.fc44 · LGPL-2.1-or-later
opensuse-leap 16.0: vhostmd 1.2-160000.2.2 · LGPL-2.1-or-later
opensuse-leap 16.0: vhostmd 1.2-160000.2.2 · LGPL-2.1-or-later
opensuse-leap 16.0: vhostmd 1.2-160000.2.2 · LGPL-2.1-or-later
opensuse-leap 16.0: vhostmd 1.2-160000.2.2 · LGPL-2.1-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms