diff --git a/DC-Micro-vhostmd b/DC-Micro-vhostmd
new file mode 100644
index 000000000..4a44c6f8a
--- /dev/null
+++ b/DC-Micro-vhostmd
@@ -0,0 +1,8 @@
+MAIN="vhostmd.asm.xml"
+SRC_DIR="articles"
+IMG_SRC_DIR="images"
+
+STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
+DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat"
+PROFOS="slmicro"
+PROFCONDITION="alp-deployment-all"
\ No newline at end of file
diff --git a/articles/vhostmd.asm.xml b/articles/vhostmd.asm.xml
new file mode 100644
index 000000000..829f58c73
--- /dev/null
+++ b/articles/vhostmd.asm.xml
@@ -0,0 +1,234 @@
+
+
+
+
+ %entities;
+]>
+
+
+
+
+
+
+
+
+
+
+
+ About vhostmd
+
+
+ Metrics format
+
+
+
+
+
+ Installation
+
+
+ Pass metrics to VM
+
+
+
+
+
+ Configuring vhostmd
+
+
+
+
+
+ Legal Notice
+
+
+ GNU Free Documentation License
+
+
+
+
+
+ Setting Up Virtual Host Metrics Daemon on &productname;
+
+
+
+ 2024-10-14
+
+
+
+ Initial version
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ &x86-64;
+ &power;
+ &aarch64;
+
+
+
+ &productname;
+
+ Setting Up Virtual Host Metrics Daemon
+ vhostmd is a tool that collects metrics from a virtual machine host
+ and provides these metrics to virtual machines running on that host.
+ vhostmd is a tool for collecting metrics
+
+
+ Systems Management
+
+
+
+ Configuration
+ Installation
+
+ Products & Solutions
+
+
+
+ https://bugzilla.suse.com/enter_bug.cgi
+ Documentation
+ SUSE Linux Enterprise Micro 6.1
+
+ jsindelarova@suse.com
+
+ yes
+
+
+
+
+ WHAT?
+
+
+ vhostmd is a tool that collects metrics from a virtual machine host
+ and can provide these metrics to the virtual machines running on that host.
+
+
+
+
+ WHY?
+
+
+ The article describes how to install and configure vhostmd to
+ enable collecting metrics.
+
+
+
+
+ EFFORT
+
+
+ It takes approximately 15 minutes to read the article.
+
+
+
+
+ GOAL
+
+
+ You will have the vhostmd tool running and collecting metrics.
+
+
+
+
+ REQUIREMENTS
+
+
+
+
+ a running instance of &productname;
+
+
+
+
+ virtual machines running on that instance
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/concepts/vhostmd_about.xml b/concepts/vhostmd_about.xml
new file mode 100644
index 000000000..d8c3dc298
--- /dev/null
+++ b/concepts/vhostmd_about.xml
@@ -0,0 +1,41 @@
+
+
+
+
+ %entities;
+]>
+
+
+
+
+
+
+ What is a virtual host metrics daemon aka <literal>vhostmd</literal>?
+
+
+
+
+
+
+
+
+
+vhostmd is a daemon that runs in a host environment and provides a metrics
+communication channel between the host and guest machines. The daemon provides the guest
+machine administrator with a limited set of host resource usage data (usually in read-only mode),
+to help analyze issues with the guest machine.
+
+
+ vhostdmd periodically writes metrics to a disk. The metrics to be
+ collected, along with the
+ frequency and storage location of the data, are configurable parameters.
+
+
diff --git a/concepts/vhostmd_data_format.xml b/concepts/vhostmd_data_format.xml
new file mode 100644
index 000000000..97acfdd7d
--- /dev/null
+++ b/concepts/vhostmd_data_format.xml
@@ -0,0 +1,126 @@
+
+
+
+
+ %entities;
+]>
+
+
+
+
+
+
+ How are the collected metrics stored?
+
+
+
+
+ The topic provides details on the metrics data format and XML output
+ structure.
+
+
+
+
+ vhostmd stores the collected metrics data on the metrics disk in a raw
+ format. The disk contains a 32-byte header followed by the metrics data in XML format.
+
+
+Metrics XML format
+
+ The collected metrics results are similar to the configured metrics definition. The <metric>
+ element can have the following attributes:
+
+
+
+ type
+
+
+ Denotes the data type of the particular metric, for example, string.
+
+
+
+
+ context
+
+
+ Identifies whether the metric is collected on the host (host) or on a virtual machine (vm).
+
+
+
+
+ id
+
+
+ Used in the vm context. Conveys the ID number of the virtual machine.
+
+
+
+
+ uuid
+
+
+ Used in the vm context. Conveys the Universally Unique Identifier of the virtual machine.
+
+
+
+
+
+ The <metric> element contains the following elements:
+
+
+
+ <name>
+
+
+ Conveys the metric name.
+
+
+
+
+ <value>
+
+
+ Conveys the metrics actual value.
+
+
+
+
+
+ No multiple values within one metric
+
+ When the group type of a metric has been configured, each configured <variable> is stored
+ as a separate metric in the result. For example, the following configuration snippet:
+
+
+<metric type="group" context="host">
+ <name>PageRates</name>
+ <action>pagerate.pl</action>
+ <variable name="PageInRate" type="uint64"/>
+ <variable name="PageFaultRate" type="uint64"/>
+</metric>
+
+
+ Results in the following snippet:
+
+
+<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>
+
+
+
+
+
diff --git a/references/vhostmd_configuration.xml b/references/vhostmd_configuration.xml
new file mode 100644
index 000000000..485fdfc93
--- /dev/null
+++ b/references/vhostmd_configuration.xml
@@ -0,0 +1,212 @@
+
+
+
+
+ %entities;
+]>
+
+
+
+
+
+
+ Configuration of <literal>vhostmd</literal>
+
+
+
+
+ The topic covers the configuration of metrics and data location.
+
+
+
+
+ The default configuration file of vhostmd is located in
+ /etc/vhostmd/vhostmd.conf. You can adjust this file to suit your needs. The configuration file is an XML file that must
+ include the <vhostmd> element. <vhostmd> then
+ includes <globals> and <metrics> that are
+ described in the following sections. Use the default configuration file as a reference for
+ custom changes.
+
+
+
+ The <literal><globals></literal> element
+
+ The <globals> element defines the disk storage location, data update
+ frequency and the method of transporting data
+ to guest machines. It contains the following elements:
+
+
+
+
+ <disk>
+
+
+The element is used to define the path of the disk where metrics data is stored and also the size
+of the disk. It may contain the following elements:
+
+
+
+
+ <name> — defines the name of the disk
+
+
+
+
+ <path> — an absolute path where the disk is mounted
+
+
+
+
+ <size> — using the unit attribute,
+ specify the maximum size of the metrics. Use k for KB,
+ m for MB.
+
+
+
+
+
+
+ <update_period>
+
+
+ Defines how often the metrics are updated. The value is in seconds.
+
+
+
+
+ <transport>
+
+
+ Specifies how the metrics are transported to guest machines. In the case of
+ &productname;, use the default of virtio.
+
+
+
+
+ <virtio>
+
+
+Here you can use the following elements:
+
+
+
+
+ <max_channels>—specifies the maximum number virtion can use
+ between the host and guest systems.
+
+
+
+
+ <expiration_time>—defines the time interval after which a
+ virtio channel of a virtual machine is closed when being idle. The default value is
+ three times the <update_period>.
+
+
+
+
+
+
+
+
+ The <literal><metrics></literal> element
+
+ The <metrics> element contains a list of metrics to be collected. Each
+ metric has two attributes:
+
+
+
+ type
+
+
+Describes the metrics value data type. Possible values are the following: int32,
+uint32, int64, uint64,
+real32, real64, string,
+group and xml.
+
+
+ Use group when a metric returns several values.
+ xml is a versatile form when the metric returns a valid XML.
+
+
+
+
+ context
+
+
+ Defines where the particular metric is collected. Possible values are:
+
+
+
+
+ host for metrics collected on the host machine
+
+
+
+
+ vm for metrics collected on the guest machine
+
+
+
+
+
+
+
+
+ Each metric must have a unique name and a command to run to record the metrics. The following
+ list describes possible elements to define a metric:
+
+
+
+ <name>
+
+
+Defines the unique variable name. If the metric is collected on a virtual machine, you can use the
+following values here: NAME, ID and UUID.
+Those values are then replaced with the actual ones of the virtual machine currently being checked.
+
+
+
+
+ <action>
+
+
+Specifies a command or script to run to collect a metric. For example,
+to gather total CPU time, use:
+
+ <action>virsh dominfo NAME | sed 's/: */:/' | \
+ gawk -F: '/CPU time/ {print $2;}'<action>
+
+
+
+ <variable>
+
+
+ if an action retuns a group of values, define variables that store particular data. The
+ element needs to have the following attributes defined:
+
+
+
+
+ name — specify the name of a variable
+
+
+
+
+ type — specify the data type of the variable
+
+
+
+
+
+
+
+
+
diff --git a/tasks/vhostmd_installation.xml b/tasks/vhostmd_installation.xml
new file mode 100644
index 000000000..74016d14c
--- /dev/null
+++ b/tasks/vhostmd_installation.xml
@@ -0,0 +1,109 @@
+
+
+
+
+ %entities;
+]>
+
+
+
+
+
+
+ Getting <literal>vhostmd</literal>
+
+
+
+
+ The topic covers installation of vhostmd on &productname;.
+
+
+
+
+ By default, vhostmd is not included in the delivered
+ images. Therefore, you must install it before using it:
+
+
+
+
+ Install the daemon by running:
+
+
+&prompt.sudo;transactional-update pkg install vhostmd
+
+
+
+
+ Reboot your system to switch to the new snapshot.
+
+
+
+
+ Start the daemon by running:
+
+
+&prompt.sudo;vhostmd OPTIONS
+
+
+ You can use the following options to modify the command behavior:
+
+
+
+
+ -v — for a verbose output
+
+
+
+ --connect URI—to pass the URI of the
+ libvirt daemon to establish connections to the daemon
+
+
+
+ -f FILE_PATH — to pass an alternative
+ configuration file. For details regarding configuration, refer to .
+
+
+
+
+ -p PID_FILE — to create an alternative
+ PID file. The default is /var/run/vhostmd.pid.
+
+
+
+
+ -u USERNAME — to use a non-privileged user
+
+
+
+
+
+
+
+ You can also run vhostmd as &systemd; service:
+
+
+&prompt.sudo;systemctl enable --now vhostmd
+
+
+
+ Service restart needed after configuration changes
+
+ Whenever you perform changes to configuration as described in , restart the vhostmd service as follows:
+
+
+&prompt.sudo;systemctl restart vhostmd
+
+
+
+
+
diff --git a/tasks/vhostmd_providing_information.xml b/tasks/vhostmd_providing_information.xml
new file mode 100644
index 000000000..36859d3b9
--- /dev/null
+++ b/tasks/vhostmd_providing_information.xml
@@ -0,0 +1,70 @@
+
+
+
+
+ %entities;
+]>
+
+
+
+
+
+
+ Providing collected metrics to a virtual machine
+
+
+
+
+ The topic covers steps to make collected metrics visible to a virtual machine.
+
+
+
+
+ You can make the collected metrics visible to particular virtual machines for further use or
+ just for reading. There are two ways to achieve this. You can either attach the
+ metrics disk using the &virsh; command or adjust the domain configuration.
+
+
+ To attach the metrics disk in a read-only mode, run &virsh; as follows:
+
+
+&prompt.sudo;virsh attach-disk VIRTUAL_MACHINE \
+ PATH_TO_METRICS_DISC --driver tap \
+ --subdriver aio --type disk --mode readonly
+
+
+
+ To change the domain configuration, proceed as follows:
+
+
+
+ Run the command
+ &prompt.sudo;virsh edit
+ GUEST_NAME
+
+
+
+ Update the <devices> section by adding the following snippet:
+
+
+<disk type='block' device='disk'>
+ <source dev='/dev/shm/vhostmd0'/>
+ <target dev='hdb' bus='ide'/>
+ <readonly/>
+</disk>
+
+
+ Adjust the dev and dbus values of the target.
+
+
+
+