<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" />
<title>Vmware-Monitor for Xymon (VMX)</title>
<meta name="author" content="Thomas Eckert <thomas.eckert@it-eckert.de>" />
<meta name="date" content="2010-10-21" />
<meta name="copyright" content="Copyright © 2009, 2010 Thomas Eckert, http://www.it-eckert.de/" />
<style type="text/css">
/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 5951 2009-05-18 18:03:10Z milde $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first {
/* Override more specific margin styles with "! important". */
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
font-weight: bold }
*/
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin: 0 0 0.5em 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left, .figure.align-left{
clear: left ;
float: left ;
margin-right: 1em }
img.align-right, .figure.align-right {
clear: right ;
float: right ;
margin-left: 1em }
.align-left {
text-align: left }
.align-center {
clear: both ;
text-align: center }
.align-right {
text-align: right }
/* reset inner alignment in figures */
div.align-right {
text-align: left }
/* div.align-center * { */
/* text-align: left } */
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font: inherit }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
ul.auto-toc {
list-style-type: none }
</style>
<style type="text/css">
/*
* :Author: Thomas Eckert, http://www.it-eckert.de/
* :Contact: thomas.eckert@it-eckert.de
* :Copyright: This stylesheet has been placed in the public domain.
* :Version: 0.9.9
*
* Stylesheet for use with Docutils.
* Vmware-Monitor for Xymon (VMX) documentation CSS.
* */
body {
font-family: sans-serif;
font-size: 100%;
background-color: #FFFFFF;
color: #000;
margin: 10px;
padding: 0;
}
a {
//color: #ff8500;
color: #355f7c;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
div.warning {
background-color: #ffe4e4;
border: 1px solid #f66;
}
div.admonition-code p.admonition-title {
//display: inline;
background-color: #888888;
padding: 10px;
}
pre.literal-block {
background-color: #cccccc;
padding: 0.3em;
}
div.admonition-code {
background-color: #cccccc;
padding: 0.3em;
//border: 1px solid #ff8500;
border: none;
font-family: monospace;
}
div.footer {
text-align: right;
}
ul {
list-style-type: square;
}
</style>
</head>
<body>
<div class="header">
Documentation for <em>Vmware-Monitor for Xymon (VMX)</em> 1.1.0
<hr class="header"/>
</div>
<div class="document" id="vmware-monitor-for-xymon-vmx">
<h1 class="title">Vmware-Monitor for Xymon (VMX)</h1>
<h2 class="subtitle" id="an-extension-for-xymon-to-monitor-vmware-hosts"><em>an extension for Xymon to monitor VMware hosts</em></h2>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr class="field"><th class="docinfo-name">Description:</th><td class="field-body">Documentation for Vmware-Monitor for Xymon (VMX)</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
<td>Thomas Eckert <<a class="reference external" href="mailto:thomas.eckert@it-eckert.de">thomas.eckert@it-eckert.de</a>></td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td>VMX-related questions to <<a class="reference external" href="mailto:vmx@it-eckert.de">vmx@it-eckert.de</a>></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2010-10-21</td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>1.1.0</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright © 2009, 2010 Thomas Eckert, <a class="last reference external" href="http://www.it-eckert.de/">http://www.it-eckert.de/</a></td></tr>
<tr class="field"><th class="docinfo-name">Info:</th><td class="field-body">see <<a class="reference external" href="http://www.it-eckert.de/software/vmx">http://www.it-eckert.de/software/vmx</a>> for more information</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#overview" id="id8">1 Overview</a></li>
<li><a class="reference internal" href="#features" id="id9">2 Features</a></li>
<li><a class="reference internal" href="#license" id="id10">3 License</a></li>
<li><a class="reference internal" href="#design" id="id11">4 Design</a></li>
<li><a class="reference internal" href="#installation" id="id12">5 Installation</a><ul class="auto-toc">
<li><a class="reference internal" href="#requirements" id="id13">5.1 Requirements</a><ul class="auto-toc">
<li><a class="reference internal" href="#server-component-vmware-monitord" id="id14">5.1.1 server-component (<tt class="docutils literal"><span class="pre">vmware-monitord</span></tt>)</a></li>
<li><a class="reference internal" href="#client-component-vmware-monitorc" id="id15">5.1.2 client-component (<tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt>)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installing-the-server" id="id16">5.2 installing the server</a><ul class="auto-toc">
<li><a class="reference internal" href="#data-processing" id="id17">5.2.1 data-processing</a></li>
<li><a class="reference internal" href="#graphing" id="id18">5.2.2 graphing</a></li>
<li><a class="reference internal" href="#installing-help-related-files-optional" id="id19">5.2.3 installing help-related files (optional)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installing-the-client" id="id20">5.3 installing the client</a><ul class="auto-toc">
<li><a class="reference internal" href="#performance-considerations-for-vma" id="id21">5.3.1 Performance considerations for vMA</a></li>
<li><a class="reference internal" href="#testing-the-connection-to-vmware-hosts-and-finalizing-the-client-installation" id="id22">5.3.2 Testing the connection to VMware hosts and finalizing the client-installation</a></li>
<li><a class="reference internal" href="#possible-problems-and-solutions" id="id23">5.3.3 Possible problems and solutions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#local-mode-setup" id="id24">5.4 local-mode setup</a></li>
<li><a class="reference internal" href="#quick-check-if-everything-is-running-on-the-xymon-server" id="id25">5.5 Quick check if everything is running on the Xymon server</a></li>
<li><a class="reference internal" href="#vmx-configuration-with-vmware-monitor-cfg" id="id26">5.6 VMX configuration with <tt class="docutils literal"><span class="pre">vmware-monitor.cfg</span></tt></a><ul class="auto-toc">
<li><a class="reference internal" href="#security-considerations-and-download-prevention" id="id27">5.6.1 security considerations and "download-prevention"</a></li>
<li><a class="reference internal" href="#client-options-for-vmware-monitorc" id="id28">5.6.2 client-options (for <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt>)</a></li>
<li><a class="reference internal" href="#server-options-for-vmware-monitord" id="id29">5.6.3 server-options (for <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt>)</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#graphing-options" id="id30">6 Graphing options</a></li>
<li><a class="reference internal" href="#usage" id="id31">7 Usage</a><ul class="auto-toc">
<li><a class="reference internal" href="#columns-explained" id="id32">7.1 Columns explained</a></li>
<li><a class="reference internal" href="#statistics-reported-in-vmwareo" id="id33">7.2 Statistics reported in "vmwareO"</a></li>
</ul>
</li>
<li><a class="reference internal" href="#manual-testing-advanced-debugging" id="id34">8 Manual testing / advanced debugging</a></li>
<li><a class="reference internal" href="#legal" id="id35">9 Legal</a></li>
</ul>
</div>
<div class="section" id="overview">
<h1><a class="toc-backref" href="#table-of-contents">1 Overview</a></h1>
<p><a class="reference external" href="http://www.it-eckert.de/software/vmx"><em>Vmware-Monitor for Xymon (VMX)</em></a> is an extension/addon for the <em>Xymon systems- and network-monitoring
system</em> <<a class="reference external" href="http://www.xymon.com/">http://www.xymon.com/</a>> providing a complete monitoring of a virtual
environment based on VMware ESX or VMware-Server without installing additional
software on the monitored hosts.</p>
<p>This monitoring includes tracking of the CPU- and RAM-usage for each running
virtual machine (columns <tt class="docutils literal">vm_cpu</tt> and <tt class="docutils literal">vm_mem</tt>), an overview for each
VMware-host (column <tt class="docutils literal">vmware</tt>) and a one-click overview for all monitored
VMware hosts (column <tt class="docutils literal">vmwareO</tt>). For each indiviual VM there is also a
<tt class="docutils literal">vm_status</tt> column that provides additional information about hat VM (like
vmware-tools status, number of VMDKs and vCPUs, ...).</p>
<p>Started and stopped VMs are also recognized as are moves of VMs between
hosts (no matter if that move was initiated manually, by vMotion or an other
mechanism).</p>
<p>The results are displayed in five additional status-columns on your Xymon
webinterface. These columns are hyperlinked so that it is very easy to navigate
back and forth in the "dependency-tree" of your virtual environment.</p>
</div>
<div class="section" id="features">
<h1><a class="toc-backref" href="#table-of-contents">2 Features</a></h1>
<p>Currently available features/highlights in <em>Vmware-Monitor for Xymon (VMX)</em>.</p>
<ul>
<li><p class="first">supports VMware ESX 3.5/ESXi 3.5, ESX 4.0/ESXi 4.0 (vSphere)</p>
</li>
<li><p class="first">VMware-server-2.0.x is unofficially supported by vMA 4.0 without
service-pack. VMware-server was never officially supported by VMware and with
SP1 for the vMA 4.0 it stopped working.</p>
</li>
<li><p class="first">no modification on VMware hosts needed (no support/warranty implications)</p>
</li>
<li><p class="first">uses official method provided by VMware (again: support-friendly)</p>
</li>
<li><p class="first">current CPU- and memory-usage, both of the ensemble of all VMware hosts, for
each individual host and each running VM (and graphical trending of these and
more of course)</p>
</li>
<li><p class="first">warning if a host is in maintainance-mode or has the "reboot-needed" flag set</p>
</li>
<li><p class="first">tracking of VM start/stop/move on each VMware host (no matter if the VM was
moved by vmotion, DRS, manually added/removed). So it's possible to easily
determine when a VM was started or stopped on (or moved to) a particular
host.</p>
</li>
<li><p class="first">vMEM/pMEM-ratio, i.e. how much of the physically available RAM is assigned to
the running VMs per VMware host</p>
</li>
<li><p class="first">one-click overview/summary of the complete monitored VMware environment on
one overview-page with the following data:</p>
<p>For each VMware host monitored overview-line with the following metrics is
available:</p>
<ul class="simple">
<li>number of running VMs (and vCPUs)</li>
<li>available CPU and RAM-resources</li>
<li>current CPU- and RAM-usage</li>
<li>number of monitored VMware hosts</li>
<li>total CPU (MHz) available</li>
<li>CPU (MHz) used</li>
<li>software version/patch-level of each VMware host</li>
<li>CPU model</li>
</ul>
<p>A summary of all monitored hosts is available with the following data:</p>
<ul class="simple">
<li>total vCPU-count running</li>
<li>total physical RAM available</li>
<li>virtual RAM used</li>
</ul>
</li>
<li><p class="first">overview-page for each VMware host along w/ it's status and the currently
running VMs</p>
</li>
<li><p class="first">central configuration of VMware-monitoring on the Xymon server</p>
</li>
<li><p class="first">perfect integration with Xymon monitoring system</p>
</li>
<li><p class="first">easy, quick and clean (non-intrusive) installation</p>
</li>
<li><p class="first">ressource friendly: low monitoring overhead due to non-forking design on the
server-side and minimized disk-access to avoid I/O problems</p>
</li>
<li><p class="first">in the (unlikely) case the Xymon setup does _not_ use FQDN (FQDN!="TRUE" in
hobbitserver.cfg) this is handled seemlessly</p>
</li>
</ul>
</div>
<div class="section" id="license">
<h1><a class="toc-backref" href="#table-of-contents">3 License</a></h1>
<p>You are allowed to evaluate <a class="reference external" href="http://www.it-eckert.de/software/vmx"><em>Vmware-Monitor for Xymon (VMX)</em></a> for up to 60 days without any limitations.
If it proves useful for you then you are required to obtain a license in order
to be allowed to use it on a regular basis.</p>
<p>For details on licencing please see <<a class="reference external" href="http://www.it-eckert.de/software/vmx">http://www.it-eckert.de/software/vmx</a>></p>
</div>
<div class="section" id="design">
<h1><a class="toc-backref" href="#table-of-contents">4 Design</a></h1>
<p><a class="reference external" href="http://www.it-eckert.de/software/vmx"><em>Vmware-Monitor for Xymon (VMX)</em></a> is designed as a client-server plugin for Xymon.</p>
<p>The <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt> (client) collects data from the VMware hosts (ESX or
VMware-Server) via the offical VMware APIs on the offical vSphere Management
Assistant (vMA) (see <a class="footnote-reference" href="#id6" id="id1">[1]</a> for more information). The collected data is sent to
the Xymon server (through the "user"-channel) where the data is received by the
<tt class="docutils literal"><span class="pre">vmware-monitord</span></tt> (server).</p>
<p>The actual status messages are then generated and sent to the (local) Xymon
server by <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt>.</p>
<p>Starting with v1.1.0 of <em>Vmware-Monitor for Xymon (VMX)</em> an alternative setup (called "local-mode"-setup)
is possible to ease the deployment in Hobbit setups: <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt> can
now be installed on the vMA. This eliminates the dependency on user-channel
patches on the (central) hobbit-server. Instead the setup on the vMA is
extended to included a stripped-down server (with user-channel support). See
<a class="reference internal" href="#local-mode-setup">local-mode setup</a> for details.</p>
</div>
<div class="section" id="installation">
<h1><a class="toc-backref" href="#table-of-contents">5 Installation</a></h1>
<p>As for every installation: backup the files you intend to change / even better
make a complete backup of your Xymon-installation before you begin. This is not
absolutely necessary as there is not automatic installation routine and so you
have full control what is changed -- but backups are always a good idea before
changing anything in a production environment (if you just want to test <em>Vmware-Monitor for Xymon (VMX)</em>
you could install -- or maybe clone if your Xymon server is installed as a VM
already -- a VM with a fresh install of Xymon).</p>
<p>As a completely risk-free option you could (probably <em>should</em>) build a
vmware-monitoring-only environment (at lest for testing) by setting up a fresh
Xymon server and vMA and install <em>Vmware-Monitor for Xymon (VMX)</em> on that "island". In that case I would
suggest to install the current SVN-snapshot of the "4.3.0"-branch of Xymon (as
the split-ncv and user-channel fixes is already integrated there). For Gentoo
users an ebuild is included in the tarball.</p>
<p>The directory-structure of the installation-tarball is similar to that of a
standard Xymon (or hobbit) installation, so it is pretty self-explaining where
the files have to be placed. After a short requirements-section the
installation for server and client is described in detail below. This includes
instructions with the necessary modifications of the configuration files in
your Xymon installation.</p>
<div class="section" id="requirements">
<h2><a class="toc-backref" href="#table-of-contents">5.1 Requirements</a></h2>
<p>General note: The "user"-channel of Xymon is used to transfer the collected
data to the Xymon server -- if any other data is transfered on that channel
conflicts may occur. <em>Vmware-Monitor for Xymon (VMX)</em> <em>should</em> be rather robust and tolerant if "non-VMX"
messages are received. Please let me know if you encounter problems with
concurrent datagrams on the user-channel so that a solution can be developed.</p>
<div class="section" id="server-component-vmware-monitord">
<h3><a class="toc-backref" href="#table-of-contents">5.1.1 server-component (<tt class="docutils literal"><span class="pre">vmware-monitord</span></tt>)</a></h3>
<ul class="simple">
<li>gawk >=3.1.3 (various gawk-specific functionalities are used, e.g. TCP/IP
networking, fflush(), ...). By default GAWK is expected to be accessible at
<tt class="docutils literal">/bin/gawk</tt></li>
<li>Xymon/Hobbit server:</li>
</ul>
<blockquote>
<ul class="simple">
<li>xymon 4.2.3: without any patches</li>
<li>xymon-4.3.0_beta2: with "splitncv-patch" or better (the "splitncv-patch" is
included in the 4.3.0 branch of Xymon since 2009-11-14)</li>
<li>hobbit-4.2.0: due to missing SPLITNCV-functionality the included alternative
graphing-definitions have to be used</li>
</ul>
</blockquote>
<!-- -->
<blockquote>
In short: a working "user"-channel and "splitncv"-module are needed on the
Xymon server. Gentoo ebuilds for Xymon can be found in
<tt class="docutils literal">./contrib/gentoo/</tt>.</blockquote>
<ul class="simple">
<li>server-component needs to be installed on the Xymon server</li>
</ul>
</div>
<div class="section" id="client-component-vmware-monitorc">
<h3><a class="toc-backref" href="#table-of-contents">5.1.2 client-component (<tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt>)</a></h3>
<ul class="simple">
<li>vMA 4.0 from VMware or equivalent tools (namely utility-programs from
vmware-vSphere-CLI-4.0.0-161974), see <a class="footnote-reference" href="#id6" id="id2">[1]</a></li>
<li>hobbit-client-4.2.0 or better. <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt> only uses the <tt class="docutils literal">bb(1)</tt>
command to send data to the Xymon server via the "user"-channel -- this works
fine with a vanilla hobbit-4.2.0. As for <em>Vmware-Monitor for Xymon (VMX)</em> it is not necessary to upgrade
the client to Xymon. Suitable RPMs can be found at <a class="footnote-reference" href="#id7" id="id3">[2]</a></li>
<li>the <tt class="docutils literal">bash</tt>-shell of course</li>
<li>in particular you do NOT NEED the following:</li>
</ul>
<blockquote>
<ul class="simple">
<li>vCenter server</li>
<li>additional database system(s)</li>
<li>Windows Server license</li>
</ul>
</blockquote>
</div>
</div>
<div class="section" id="installing-the-server">
<h2><a class="toc-backref" href="#table-of-contents">5.2 installing the server</a></h2>
<p>The server installation consists of two logical parts:</p>
<blockquote>
<ol class="arabic simple">
<li>installing and configure the "data-processing"</li>
<li>configure the "graphing" system and the graphs to be shown</li>
</ol>
</blockquote>
<p>The data-processing is done by <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt> which runs under the control
of <tt class="docutils literal">hobbitd_channel(8)</tt> and processes the messages send by the client
(<tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt>) to generate the Xymon "status"-messages.</p>
<p>The graphing data is extracted from the status messages via the NCV-module of
Xymon (in fact SPLITNCV is used).</p>
<p>If you are using a rather dated hobbit-server without support for
"user-channel"-messages please see <a class="reference internal" href="#local-mode-setup">local-mode setup</a> for details on running
<tt class="docutils literal"><span class="pre">vmware-monitord</span></tt> on the vMA.</p>
<div class="section" id="data-processing">
<h3><a class="toc-backref" href="#table-of-contents">5.2.1 data-processing</a></h3>
<ul>
<li><p class="first">copy <tt class="docutils literal"><span class="pre">server/bin/vmware-monitord</span></tt> to <tt class="docutils literal">~/server/bin/</tt> on your Xymon server
and check if the shebang (<tt class="docutils literal"><span class="pre">#!/bin/gawk</span></tt>) fits your path to gawk and adjust
if needed. The default of <tt class="docutils literal">/bin/gawk</tt> should work on almost any Linux
distribution.</p>
</li>
<li><p class="first">enable starting of <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt> with the default 5 minute
test-interval by appending the following lines to
<tt class="docutils literal">~/server/etc/hobbitlaunch.cfg</tt> (paths may need to be adjusted to fit your
setup):</p>
<pre class="literal-block">
[vmware-monitord]
ENVFILE /usr/lib/xymon/server/etc/hobbitserver.cfg
NEEDS hobbitd
CMD hobbitd_channel --channel=user --log=$BBSERVERLOGS/vmware-monitord.log vmware-monitord
</pre>
<p>(<tt class="docutils literal"><span class="pre">vmx-hobbitlaunch.cfg</span></tt> is included to be easily appended to your config)</p>
</li>
<li><p class="first">if you have set "--status-senders=IP[/MASK][,IP/MASK]" for "hobbitd" in
hobbitlaunch.cfg you may need to add your processing-hosts IP</p>
</li>
<li><p class="first">configuration-file <tt class="docutils literal"><span class="pre">server/etc/vmware-monitor.cfg</span></tt>: 2 options:</p>
<ol class="loweralpha simple">
<li>If you want to prevent downloading of the configuration for <strong>security
reasons</strong> (it contains passwords and the Xymon-connection is not encrypted
by default) then copy the configuration file <tt class="docutils literal"><span class="pre">vmware-monitor.cfg</span></tt> to
<tt class="docutils literal">~/server/etc/</tt>. This "download-prevention" can be used for the
<tt class="docutils literal"><span class="pre">bb-hosts</span></tt>-file too, see <a class="reference internal" href="#vmx-configuration-with-vmware-monitor-cfg">VMX configuration with vmware-monitor.cfg</a>.</li>
<li>If you want to use the central-configuration, i.e. all configuration done
on the Xymon server then copy <tt class="docutils literal"><span class="pre">vmware-monitor.cfg</span></tt> to
<tt class="docutils literal">$HOBBITCLIENTHOME/etc/</tt> on the vMA.</li>
</ol>
<p>Details about needed adjustments are given in the section <a class="reference internal" href="#vmx-configuration-with-vmware-monitor-cfg">VMX
configuration with vmware-monitor.cfg</a>.</p>
</li>
<li><p class="first">add the "vmware"-test to your VMware hosts in <tt class="docutils literal"><span class="pre">~/server/etc/bb-hosts</span></tt>.</p>
</li>
</ul>
<div class="admonition-example admonition">
<p class="first admonition-title">Example</p>
<p>Let esx1.local and esx2.local be our VMware hosts. Define these 2 hosts in
our bb-hosts with the "vmware"-tag as follows:</p>
<pre class="last literal-block">
1.2.3.4 esx1.local # [ other tests ] vmware [ other tests ]
1.2.3.5 esx2.local # [ other tests ] vmware [ other tests ]
</pre>
</div>
<ul>
<li><p class="first">add your VMs with their "displaynames" from the VMware environment to
<tt class="docutils literal"><span class="pre">bb-hosts</span></tt>.</p>
<p>If your VMs displaynames are not identical with the hostnames of the VMs then
you could use <tt class="docutils literal"><span class="pre">CLIENT:<displayname></span></tt> in your <tt class="docutils literal"><span class="pre">bb-hosts</span></tt> for the VM or
(really not recommended!) add a dummy-entry with "0.0.0.0" and "noconn".</p>
</li>
</ul>
<div class="admonition-example admonition">
<p class="first admonition-title">Example</p>
<p>Your vMA has the hostname "vma.local" but after you installed the Virtual
Appliance you did not rename the VM and thus the displayname is still
"vMA-ovf-4.0.0-161993". In this case add the following to you <tt class="docutils literal"><span class="pre">bb-hosts</span></tt>:</p>
<pre class="last literal-block">
192.168.1.1 vma.local # CLIENT:"vMA-ovf-4.0.0-161993"
</pre>
</div>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p>Using the <tt class="docutils literal">CLIENT:</tt>-directive in <tt class="docutils literal"><span class="pre">bb-hosts</span></tt> to overwrite the reported
hostnames soon leads to an overly complex setup. Another negative
side-effect of using <tt class="docutils literal">CLIENT:</tt> is the breaking of hyperlinks between the
test-columns generated by <em>Vmware-Monitor for Xymon (VMX)</em>.</p>
<p class="last">So you should only use the <tt class="docutils literal">CLIENT:</tt>-directive if changing the displayname
of a VM is not possible for serious reasons.</p>
</div>
</div>
<div class="section" id="graphing">
<h3><a class="toc-backref" href="#table-of-contents">5.2.2 graphing</a></h3>
<ul>
<li><p class="first">copy <tt class="docutils literal"><span class="pre">server/etc/hobbitgraph.d/vmware-monitor-graph.cfg</span></tt> to your
<tt class="docutils literal">hobbitgraph.d</tt>-directory if you use <tt class="docutils literal">directory <span class="pre"><path-to-hobbitgraph.d></span></tt>
in your <tt class="docutils literal">~/server/etc/hobbitgraph.cfg</tt>.
CAUTION: after the <tt class="docutils literal">directory</tt>-statement there is only <em>one space</em> allowed!</p>
<p>OR:</p>
<p>append the contents of <tt class="docutils literal"><span class="pre">server/etc/hobbitgraph.d/vmware-monitor-graph.cfg</span></tt>
to <tt class="docutils literal">~/server/etc/hobbitgraph.cfg</tt></p>
</li>
<li><p class="first">adjust <tt class="docutils literal">~/server/etc/hobbitserver.cfg</tt> as follows: using cut-n-paste from
the included <tt class="docutils literal"><span class="pre">server/etc/vmx-hobbitserver.cfg</span></tt> is probably the savest way
as this documentation is aimed at printing and web-display; take special care
with line continuation characters!</p>
</li>
</ul>
<blockquote>
<ol class="loweralpha">
<li><p class="first">append to variable <tt class="docutils literal">TEST2RRD</tt>:</p>
<pre class="literal-block">
,vmwareO=ncv,vmware=ncv,vm_cpu=ncv,vm_mem=ncv
</pre>
</li>
<li><p class="first">insert the following lines (e.g. right after <tt class="docutils literal">TEST2RRD</tt>):</p>
<pre class="literal-block">
## Vmware-Monitor for Xymon (VMX):
## append "vmwareO=ncv,vmware=ncv,vm_cpu=ncv,vm_mem=ncv" to TEST2RRD
SPLITNCV_vmwareO="vmwarehosts:GAUGE,physcpuavail:GAUGE,physcpuused:GAUGE,physcpuused_pct:GAUGE,\
physramavail:GAUGE,physramused:GAUGE,physramused_pct:GAUGE,\
numbervms:GAUGE,vcpurunning:GAUGE,runtime_c:GAUGE,runtime_d:GAUGE,*:NONE"
SPLITNCV_vmware="cpuuse:GAUGE,memuse:GAUGE,cpuuse_pct:GAUGE,memuse_pct:GAUGE,\
numbervms:GAUGE,vcpurunning:GAUGE,bla:DERIVE,*:NONE"
SPLITNCV_vm_cpu="cpuuse:GAUGE,vcpurunning:GAUGE,*:NONE"
SPLITNCV_vm_mem="memuse:GAUGE,memuse_pct:GAUGE,*:NONE"
## Vmware-Monitor for Xymon (VMX) end.
</pre>
</li>
</ol>
</blockquote>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">DO NOT use line continuation characters ("<tt class="docutils literal">\</tt>") in <tt class="docutils literal">hobbitserver.cfg</tt>,
these are only used to make the documentation more readable.</p>
</div>
<!-- -->
<ul class="simple">
<li>if you want the vmware-related graphs to show up on the "trends" column you
have to add them to the GRAPHS-variable in ~/server/etc/hobbitserver.cfg.</li>
</ul>
<div class="admonition-example admonition">
<p class="first admonition-title">Example</p>
<p>append:</p>
<pre class="literal-block">
,vmware::10,vmwareO::10,vm_cpu,vm_mem
</pre>
<p>to the <tt class="docutils literal">GRAPHS</tt> variable.</p>
<p class="last">Or insert them at a position of your choice in <tt class="docutils literal">GRAPHS</tt>, e.g.
"vmware,vmwareO" at the beginning and insert "vm_cpu" right after "la" and
"vm_mem" after "memory".</p>
</div>
<!-- -->
<blockquote>
In your <tt class="docutils literal"><span class="pre">bb-hosts</span></tt>-file you could also make use of the <tt class="docutils literal">TRENDS:</tt>-statements.</blockquote>
<div class="admonition-example admonition">
<p class="first admonition-title">Example</p>
<p>You could append:</p>
<pre class="literal-block">
TRENDS:\*,vmwareO:vmwareO_cpu|vmwareO_mem|vmwareO_counters|vmwareO_runtime
</pre>
<p class="last">to show all available graphs for <tt class="docutils literal">vmwareO</tt> in a more readable form.
A slight problem with empty/broken graphs showing up in this case needs to
be investigated and fixed though.</p>
</div>
<!-- -->
<blockquote>
TODO: XXX: elimnate * above!</blockquote>
<ul class="simple">
<li>restart Xymon on the server (<tt class="docutils literal">/etc/init.d/xymon restart</tt> or whatever
mechanism you use) to activate the changes</li>
</ul>
</div>
<div class="section" id="installing-help-related-files-optional">
<h3><a class="toc-backref" href="#table-of-contents">5.2.3 installing help-related files (optional)</a></h3>
<p>The installation of help-files is not needed for the bare functionality but
often comes handy.</p>
<p>For a short column-description you may append the contents of
<tt class="docutils literal"><span class="pre">server/etc/vmx-columndoc.csv</span></tt> to your <tt class="docutils literal">~/server/etc/columndoc.csv</tt> to
provide a short explanation for each test-column generated by <em>Vmware-Monitor for Xymon (VMX)</em>.</p>
<p>To include a link to the online-help from the "Help"-menu in Xymon's
webinterface just copy <tt class="docutils literal">server/www/help/vmx/index.html</tt> to
<tt class="docutils literal">~/server/www/help/vmx/</tt> (the directory <tt class="docutils literal">vmx</tt> needs to be created) and add
an entry like the following to the "Help"-section in
<tt class="docutils literal">~/server/www/menu/menu_items.js</tt>:</p>
<pre class="literal-block">
['VMX', '/xymon/help/vmx/'],
</pre>
<p>(adjust the URL <tt class="docutils literal">/xymon/help/vmx/</tt> to fit your setup)</p>
</div>
</div>
<div class="section" id="installing-the-client">
<h2><a class="toc-backref" href="#table-of-contents">5.3 installing the client</a></h2>
<ul>
<li><p class="first">install vMA somewhere (see <a class="footnote-reference" href="#id6" id="id4">[1]</a> for additional notes)</p>
</li>
<li><p class="first">install hobbit-/xymon-client on vMA (hobbit-4.2.0+ is fine)
and configure the client to report to your Xymon server (see <a class="footnote-reference" href="#id7" id="id5">[2]</a> for
download link for RPMs.</p>
<p>Note: for example the xymon-client-4.2.3 rpm is configured in
<tt class="docutils literal"><span class="pre">/etc/sysconfig/xymon-client</span></tt>; after changing this file at least one start
of the client via the init.d-script is necessary to create the needed
runtime-files.</p>
</li>
<li><p class="first">copy <tt class="docutils literal"><span class="pre">client/ext/vmware-monitorc</span></tt> to <tt class="docutils literal">~/client/ext/</tt>-dir on your vMA</p>
</li>
<li><p class="first">add <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt> to <tt class="docutils literal">~/client/etc/clientlaunch.cfg</tt> on vMA to send
data to the server by appending the following:</p>
<pre class="literal-block">
[vmware-monitorc]
ENVFILE $HOBBITCLIENTHOME/etc/hobbitclient.cfg
CMD $HOBBITCLIENTHOME/ext/vmware-monitorc -s
LOGFILE $HOBBITCLIENTHOME/logs/vmware-monitorc.log
INTERVAL 5m
</pre>
<p>(<tt class="docutils literal"><span class="pre">vmx-clientlaunch.cfg</span></tt> is included to be easily appended to your config)</p>
</li>
<li><p class="first">add your vMA to <tt class="docutils literal"><span class="pre">bb-hosts</span></tt> on the Xymon server of course</p>
</li>
<li><p class="first">for security reasons you may want to put the configuration file
<tt class="docutils literal"><span class="pre">vmware-monitor.cfg</span></tt> into <tt class="docutils literal">~/client/etc/</tt> on the vMA (see <a class="reference internal" href="#vmware-monitor-cfg">vmware-monitor.cfg</a>
in the <a class="reference internal" href="#data-processing">data-processing</a> section above for details).</p>
</li>
</ul>
<div class="section" id="performance-considerations-for-vma">
<h3><a class="toc-backref" href="#table-of-contents">5.3.1 Performance considerations for vMA</a></h3>
<p>[ Note: The information in this section is not relevant for a VMware
environment of up to 4 hosts with a reasonable load. It might be interresting
to tune your setup anyway but it is not necessary for normal operations. ]</p>
<p>Querying the VMware hosts for all the required data can generate significant
load on the vMA. In addition it takes several seconds to fetch all the data
needed from one single host (the individual runtime depends on a variety of
factors, around 20 seconds is common). This becomes a problem if a large number
of hosts are monitored as the time to query all hosts might exceed the 5 minute
test-interval of Xymon.</p>
<p>For that reason <em>Vmware-Monitor for Xymon (VMX)</em> has the possibility to query VMware hosts in parallel.
This feature is disabled by default (<tt class="docutils literal">CLIENT_CONCURRENCY=1</tt>).</p>
<p>In a 7 ESX 3.5 environment the runtime of <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt> is roughly 145
seconds with a very low load on the vMA-VM. Increasing the concurrenty to 4
only gives a few seconds of runtime-savings but a highly (over) loaded vMA.
Adding a 2nd vCPU to the vMA (and increasing the memory of the VM to 1 GB) the
runtime drops below 1 minute with a load on the vMA in reasonabe ranges.</p>
<p>In short: if the concurrency of <tt class="docutils literal"><span class="pre">vmware-montirc</span></tt> is increased to reduce
<tt class="docutils literal">runtime_c</tt> adjustments to the vMA-VM might be needed to avoid overload that
prevents a runtime-reduction.</p>
</div>
<div class="section" id="testing-the-connection-to-vmware-hosts-and-finalizing-the-client-installation">
<h3><a class="toc-backref" href="#table-of-contents">5.3.2 Testing the connection to VMware hosts and finalizing the client-installation</a></h3>
<p>After installing the client-stuff it is time to test if data can be
fetched from the VMware hosts at all. Login to your vMA and su to the hobbit-
or xymon-user. The following steps outline the testing-process:</p>
<ol class="arabic">
<li><p class="first">Basic test using the vCLI utility <tt class="docutils literal">hostinfo.pl</tt> to fetch data from the
hosts: adjust 192.168.1.1:443 in the example by the IP and port-number you
entered in <tt class="docutils literal"><span class="pre">bb-hosts</span></tt> and <tt class="docutils literal"><span class="pre">vmware-monitor.cfg</span></tt> respcectively and the
username and password you specified there:</p>
<pre class="literal-block">
/usr/lib/vmware-vcli/apps/host/hostinfo.pl --url https://192.168.1.1:443/sdk
</pre>
</li>
</ol>
<blockquote>
If everything works fine you'll get "Host Information" back (Host Name, Port
Number, BootTime, ...). If not check the URL (incl. the portnumber) for
spelling error and the username and password.</blockquote>
<ol class="arabic" start="2">
<li><p class="first">Run the <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt> in debug-mode so no data is sent to the Xymon
server yet. Instead everything is printed to stdout. This will fetch the
needed configuration-files from the Xymon server (or use the ones you placed
in <tt class="docutils literal">$HOBBITCLIENTHOME/etc/</tt> on the vMA) and query all VMware hosts. The
results will be printed to stdout and no data will be sent to the Xymon
server:</p>
<pre class="literal-block">
~/client/bin/bbcmd /usr/lib/hobbit/client/ext/vmware-monitorc -d
</pre>
<p>If errors occur check <a class="reference internal" href="#possible-problems-and-solutions">Possible problems and solutions</a>.</p>
</li>
<li><p class="first">Run the above command without the "-d" debug-option to send one data-set to
the Xymon server. Most likely you will have some ghost-clients for your VMs.
You can add them to the <tt class="docutils literal"><span class="pre">bb-hosts</span></tt> file or leave them as ghosts for now.</p>
</li>
<li><p class="first">If the testing above was successful start the hobbit-/xymon-client on vMA:</p>
<pre class="literal-block">
/etc/init.d/hobbit-client start (or: /etc/init.d/xymon-client start)
</pre>
</li>
</ol>
</div>
<div class="section" id="possible-problems-and-solutions">
<h3><a class="toc-backref" href="#table-of-contents">5.3.3 Possible problems and solutions</a></h3>
<p>If no data is sent to the Xymon server you can do the following:</p>
<ul>
<li><p class="first">check the logiles <tt class="docutils literal"><span class="pre">vmware-monitor.log</span></tt> both on the client and server for
errors.</p>
</li>
<li><p class="first">run the client in debug-mode and look for reported errors, e.g. the following
indicates problems with a multi-BBD-environment (see next point for
details):</p>
<pre class="literal-block">
$ ~/client/bin/bbcmd ~/client/ext/vmware-monitorc -d
2010-01-11 04:43:46 Using default environment file /usr/lib64/xymon/client/etc/hobbitclient.cfg
2010-01-11 04:43:46 ERROR: /usr/lib64/xymon/client/tmp/vmware-monitor.cfg does not exist or is empty!
</pre>
</li>
<li><p class="first"><strong>multi BBD</strong> environments: if the server installation of VMX is <strong>not done
on the 1st BBD</strong> it is required to temporarily use the
"<tt class="docutils literal"><span class="pre">vmware-monitord</span></tt>-BBD" as the 1st one in your vMA
hobbit/xymon-configuration (i.e. make sure the IP of the Xymon server running
<tt class="docutils literal"><span class="pre">vmware-monitord</span></tt> is the 1st one listed in the <tt class="docutils literal">BBDISPLAYS</tt>-variable on
your vMA). This is necessary for two reasons:</p>
</li>
</ul>
<blockquote>
<ol class="arabic simple">
<li>the central configuration uses the <tt class="docutils literal">config</tt> command of <tt class="docutils literal">bb(1)</tt> which
only uses the 1st BBD configured. The <tt class="docutils literal"><span class="pre">bb-hosts</span></tt>- and
<tt class="docutils literal"><span class="pre">vmware-monitor.cfg</span></tt>-configfiles are fetched with this mechanism by
<tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt>.</li>
<li>the data is only sent to the 1st BBD via the user-channel.</li>
</ol>
</blockquote>
</div>
</div>
<div class="section" id="local-mode-setup">
<h2><a class="toc-backref" href="#table-of-contents">5.4 local-mode setup</a></h2>
<p>Only use this <tt class="docutils literal"><span class="pre">local-mode</span></tt>-setup if there is good reason to do so. The
reasoning behind this advice is the current lack of a nice installer for the
vMA resulting in some extra manual configuration. In the future there may be an
installer for all the vMA-related configuration that eliminates (almost) all
manual steps outlined below.</p>
<ul>
<li><p class="first">install a Xymon-server package on the vMA (instead of a client-only package
for the "server-mode"-setup)</p>
</li>
<li><p class="first">install the client as described above</p>
</li>
<li><p class="first">install <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt> on the vMA instead of your central Xymon-server</p>
</li>
<li><p class="first">the license-file needs to be installed on the vMA too, ensure that the
monitoring-user has write-access to /etc/xymon/ in case you are setting up
the demo.</p>
</li>
<li><p class="first">strip-down the Xymon-server on the vMA to only run <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt></p>
<ul>
<li><p class="first">adjust <tt class="docutils literal">/etc/xymon/hobbitserver.cfg</tt>: <tt class="docutils literal">BBSERFVERIP</tt> points to our
central Xymon server(s)</p>
</li>
<li><p class="first">disable the server-processes of Xymon on the vMA in
<tt class="docutils literal">/etc/xymon/hobbitlaunch.cfg</tt>:</p>
<pre class="literal-block">
[bbhistory]
DISABLED
[hostdata]
DISABLED
[bbpage]
DISABLED
[rrdstatus]
DISABLED
[rrddata]
DISABLED
[clientdata]
DISABLED
[bbdisplay]
DISABLED
[bbcombotest]
DISABLED
[bbnet]
DISABLED
[bbretest]
DISABLED
</pre>
<p>=> all services except <tt class="docutils literal">[hobbitd]</tt> and <tt class="docutils literal">[hobbitclient]</tt> are disabled.</p>
</li>
</ul>
</li>
<li><p class="first">configure <em>Vmware-Monitor for Xymon (VMX)</em> to use <tt class="docutils literal"><span class="pre">local-mode</span></tt>: adjust <tt class="docutils literal"><span class="pre">vmware-monitor.cfg</span></tt> (still
installed on your central hobbit-server) to have <tt class="docutils literal">SERVER_MODE=0</tt>
configured.</p>
</li>
</ul>
</div>
<div class="section" id="quick-check-if-everything-is-running-on-the-xymon-server">
<h2><a class="toc-backref" href="#table-of-contents">5.5 Quick check if everything is running on the Xymon server</a></h2>
<p>On the server you should see the new file $BBSERVERLOGS/vmware-monitord.log
(e.g. /var/log/xymon/) and upon reception of the 1st usermessage from the
client 2 lines similar to the following:</p>
<div class="admonition-example admonition">
<p class="first admonition-title">Example</p>
<p>First 2 lines logged in <tt class="docutils literal"><span class="pre">vmware-monitord.log</span></tt> after the 1st dataset was
received:</p>
<pre class="literal-block">
2009-12-06 14:07:24 vmware-monitord v0.9.9 started, pid=17211, ppid=16962
2009-12-06 14:07:24 done with dataset 1
</pre>
<p class="last">TODO: XXX: update log-lines to current version</p>
</div>
<p>For the first 12 datasets a log-entry is generated for each one ("done with
dataset N"), after that only every 12th dataset is logged to reduce the
growth-rate of the logfile (only one log-entry per hour).</p>
<p>On the client the logfile is <tt class="docutils literal"><span class="pre">$HOBBITCLIENTHOME/logs/vmware-monitorc.log</span></tt>
(e.g. <tt class="docutils literal">~/client/log/</tt>).</p>
</div>
<div class="section" id="vmx-configuration-with-vmware-monitor-cfg">
<h2><a class="toc-backref" href="#table-of-contents">5.6 VMX configuration with <tt class="docutils literal"><span class="pre">vmware-monitor.cfg</span></tt></a></h2>
<p id="vmware-monitor-cfg">The configuration is split into a <em>client</em>- and <em>server</em>-section that are used
by <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt> and <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt> respectively.</p>
<p>Adjust <tt class="docutils literal"><span class="pre">vmware-monitor.cfg</span></tt> to fit your setup. Filling in the username and
password for your VMware hosts and the management-port used is required for
<em>Vmware-Monitor for Xymon (VMX)</em> to be able to fetch data from the hosts.</p>
<div class="section" id="security-considerations-and-download-prevention">
<h3><a class="toc-backref" href="#table-of-contents">5.6.1 security considerations and "download-prevention"</a></h3>
<p>As already outlined in <a class="reference internal" href="#data-processing">data-processing</a> the configuration file is tranfered
non-encrypted over the network (currently Xymon does not support encrypted
server-client-communication by itself). As login information is contained in
the configuration you may want to prevent these from being tranfered in clear
over the network. To do so use the "download-prevention" of <em>Vmware-Monitor for Xymon (VMX)</em>.</p>
<p>The "download-prevention" also works for the <tt class="docutils literal"><span class="pre">bb-hosts</span></tt>-file. So if for some
reason you want the client <em>not</em> to download an up-to-date <tt class="docutils literal"><span class="pre">bb-hosts</span></tt>-file
from the server just place a <tt class="docutils literal"><span class="pre">bb-hosts</span></tt>-file in <tt class="docutils literal">$HOBBITCLIENTHOME/etc/</tt> on
the vMA.</p>
<p>Please note that both <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt> and <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt> use the
configuration, so if you make use of "download-prevention" on the client you
still need to install <tt class="docutils literal"><span class="pre">vmware-monitor.cfg</span></tt> on the Xymon server in
<tt class="docutils literal">~/server/etc/</tt>!</p>
</div>
<div class="section" id="client-options-for-vmware-monitorc">
<h3><a class="toc-backref" href="#table-of-contents">5.6.2 client-options (for <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt>)</a></h3>
<p>The client-section of the configuration-file
<tt class="docutils literal"><span class="pre">~/server/etc/vmware-monitor.cfg</span></tt> holds the login-data to the VMware hosts
monitored and a tuning-parameter to optimize the runtime of
<tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt>.</p>
<p>It is strongly recommended to create a read-only account on your VMware hosts
for the monitoring user. Add a user (e.g. "xymon") with read-only permissions
to each of your ESX hosts).</p>
<p>You may also adjust <tt class="docutils literal">CLIENT_CONCURRENCY</tt> to tune the runtime of
<tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt>, see <a class="reference internal" href="#performance-considerations-for-vma">Performance considerations for vMA</a> for more
information.</p>
<p>Environments with multiple BBDISPLAY-servers (BBDs) may need an additional
configuration, depending on the use-case. If multiple BBDs are used to build-up
a poor-mans redundant setup where all data is sent to all BBDs you have to
configure <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt> to send data not only to the first BBD listed in
<tt class="docutils literal">$BBDISPLAYS</tt> (which btw. is the server the configuration is fetched from)
which is the default but to all of them.
This is controlled by <tt class="docutils literal">CLIENT_TOALL_BBDS</tt> in <tt class="docutils literal"><span class="pre">vmware-monitor.cfg</span></tt>. Change
the default of <tt class="docutils literal">NO</tt> to <tt class="docutils literal">YES</tt> to enable data-sending to all BBDs. Keep in
mind that the vMA will remain a single-point-of-failure though.</p>
</div>
<div class="section" id="server-options-for-vmware-monitord">
<h3><a class="toc-backref" href="#table-of-contents">5.6.3 server-options (for <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt>)</a></h3>
<p>This is the default-configuration for <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt> in the configuration-file:</p>
<pre class="literal-block">
## StartupColor: [GREEN|YELLOW]
## Color of the VMs in the 1st run of VMX
## yellow = all "vm_status" (and in turn "vmware" and "vmwareO")
## columns go yellow
## This forces xymon to record the current state => available via "history"
StartupColor="YELLOW"
## Debug:
## 0=disable debugging
## 1=function-entry
## 2=print func-returns
## 10=output of less noisy funcs
## 20=output of more noisy funcs
Debug="0"
## HostColorChangeOn*VM: [YES|NO]
## Change to color of the "vmware"-column (to yellow) if a VM is
## started/stopped/moved
HostColorChangeOnStartedVM="YES"
HostColorChangeOnStoppedVM="YES"
HostColorChangeOnMovedVM="YES"
## VMColorChangeOn*: [YES|NO]
## Change to color of the "vm_status"-column (to yellow) if a VM is
## started/stopped/moved
VMColorChangeOnStart="YES"
VMColorChangeOnStop="YES"
VMColorChangeOnMove="YES"
</pre>
</div>
</div>
</div>
<div class="section" id="graphing-options">
<h1><a class="toc-backref" href="#table-of-contents">6 Graphing options</a></h1>
<p>If you follow the installation-instructions all graphs track their values via
the "SPLITNCV"-backend of Xymon, thus each metric is stored in a separate RRD.</p>
<p>There are some alternatives available and pre-configured regarding the data
that is actually drawn on the webinterface of Xymon, e.g. if you prefer to have
the absolute values in MHz and MB or rather want to show the calculated usages
in percent.</p>
<p>Where possible graphs are available with percentage ("_pct") and absolute
("_abs") values. This is the case for all memory-graphs, all cpu-graphs except
for the cpu-graph on a single VM (it is not possible to get the number of cores
on a vmware hosts via the vSphere API and thus no usage in percent can be
calucated).</p>
<p>In <tt class="docutils literal"><span class="pre">vmware-monitor-graph.cfg</span></tt> there are already various graphs defined. See
list below for all available graphs; if alternative graphs are available the
default-graph is marked with "DEFAULT" (these graphs are named identical to the
column-name in the webinterface).</p>
<ul class="simple">
<li>vmwareO: (this column/graph is available for the vMA)<ul>
<li>[vmwareO_pct]: DEFAULT cpu- and ram-usage in percent and all counters
except runtime</li>
<li>[vmwareO_abs]: all data in absolute units (MHz, MB, count)</li>
<li>[vmwareO_cpu]: only CPU-data in absolute units</li>
<li>[vmwareO_mem]: only memory-data in absolute units</li>
<li>[vmwareO_counters]: number of VMs, hosts and vCPUs</li>
<li>[vmwareO_runtime]: runtime of <em>Vmware-Monitor for Xymon (VMX)</em> (both, client and server)</li>
</ul>
</li>
<li>vmware: (this column/graph is available for all VMware hosts)<ul>
<li>[vmware_pct]: DEFAULT is to show percentage-graph</li>
<li>[vmware_abs]: absolute values (MHz, MB)</li>
</ul>
</li>
<li>per VM graphs -- theses columns/graphs are available for all each running VM:<ul>
<li>[vm_cpu]: cpu-usage and number of assigned vCPUs</li>
<li>[vm_mem_abs] DEFAULT mem-usage (guestmemoryusage) in MB</li>
<li>[vm_mem_pct] mem-usage in %</li>
<li>[vm_status]</li>
</ul>
</li>
</ul>
<p>TODO: XXX</p>
<ul class="simple">
<li>Note about "Metrics Reports"</li>
</ul>
</div>
<div class="section" id="usage">
<h1><a class="toc-backref" href="#table-of-contents">7 Usage</a></h1>
<p>This chapter gives hints about using <em>Vmware-Monitor for Xymon (VMX)</em> and explains some details.</p>
<p>[ Work in progress: this chapter is not finished yet! ]</p>
<div class="section" id="columns-explained">
<h2><a class="toc-backref" href="#table-of-contents">7.1 Columns explained</a></h2>
<p>After the first start of our Xymon server with <em>Vmware-Monitor for Xymon (VMX)</em> installed (more precicely
after reception of the first data-set from <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt>) some additional
columns show up on your Xymon webinterface (if you followed this guide this is
already the case hopefully). These columns are documented in this section.</p>
<p>A general note about the units used:</p>
<ul class="simple">
<li>CPU-usage: "cpuuse" is always the absolute value of the usage in [MHz],
"cpuuse_pct" is percentage used of the available cpuspeed in the context of
the current view.</li>
<li>MEM-usage: "memuse" is in [MB], "memuse_pct" in percent analogous to the
CPU-values.</li>
</ul>
<p>In total there are five additional columns that show up.</p>
<dl class="docutils">
<dt>vmwareO</dt>
<dd><p class="first"><strong>Overview</strong> for all VMware hosts monitored. This column is only generated
for the host running the client <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt> -- typically your vMA.</p>
<p>Each vmware host in the overview-table at the bottom is hyper-linked to the
respective <tt class="docutils literal">vmware</tt>-column of that host.</p>
<p>Column is generated only for the machine running <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt>,
typically your vMA.</p>
<p class="last">Graphs: <tt class="docutils literal">vmwareO_pct</tt> (default), <tt class="docutils literal">vmwareO_abs</tt>,
<tt class="docutils literal">vmwareO_cpu</tt>, <tt class="docutils literal">vmwareO_mem</tt>, <tt class="docutils literal">vmwareO_counters</tt>, <tt class="docutils literal">vmwareO_runtime</tt></p>
</dd>
<dt>vmware</dt>
<dd><p class="first">A summary you get for each monitored VMware host ("esx1" and "esx2" in the
example above) that graphs cpuuse and memuse.</p>
<p>The number of vCPUs assigned to and the number of currently running VMs are
graphed, too.</p>
<p>For each VM in the "running VMs"-table at the bottom the cpuuse- (memuse-)
column links to <tt class="docutils literal">vm_cpu</tt> (<tt class="docutils literal">vm_mem</tt>) of that VM. The VMname links to
<tt class="docutils literal">vm_status</tt> of the VM. In addition the vmware-tools-status is shown in this
table.</p>
<p>An additional link to the <tt class="docutils literal">vmwareO</tt>-column of the vMA that sent the data is
somewhat hidden in the <tt class="docutils literal">>>> <span class="pre">client-script</span></tt>-line: the hostname of the
machine running <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt> is the hyperlink.</p>
<p class="last">Graphs: <tt class="docutils literal">vmware_pct</tt> (default), <tt class="docutils literal">vmware_abs</tt></p>
</dd>
<dt>vm_cpu</dt>
<dd><p class="first">CPU-usage and the number of assigned vCPUs for each individual VM running.</p>
<p>Column is generated for each running VM.</p>
<p class="last">Graphs: <tt class="docutils literal">vm_cpu</tt></p>
</dd>
<dt>vm_mem</dt>
<dd><p class="first">Memory-usage for each individual VM running (graphing in absolute
values, i.e. [MB]) and in % as an alternative.</p>
<p>Column is generated for each running VM.</p>
<p class="last">Graphs: <tt class="docutils literal">vm_mem_abs</tt> (default), <tt class="docutils literal">vm_mem_pct</tt></p>
</dd>
<dt>vm_status</dt>
<dd><p class="first">Various status-information about the VM: the host it is running on (links
back to the hosts "vmware"-column), name, path to vmx-file with datastore,
number of VMDKs, number of vCPUs, memory-size, ...</p>
<p>Status of vmware-tools and if tools are running additional information like
hostname, ipaddress, guestos, ...</p>
<p>Column is generated for each running VM.</p>
<p class="last">Graphs: <tt class="docutils literal">vm_status</tt></p>
</dd>
</dl>
</div>
<div class="section" id="statistics-reported-in-vmwareo">
<h2><a class="toc-backref" href="#table-of-contents">7.2 Statistics reported in "vmwareO"</a></h2>
<p>(TODO: _not_ complete!)</p>
<ul class="simple">
<li><tt class="docutils literal">>> <span class="pre">client-script</span> statistics:</tt></li>
</ul>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal">runtime_c</tt> is the runtime of <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt> in seconds and a metric
to keep an eye on. If the montoried VMware hosts are highly loaded the
runtime may increase significantly. For a 7-host-environment a runtime of ~2
... 2.5 minutes is reasonable. If the runtime exceeds 3 minutes tuning steps
have to take place in order to avoid problems with the 5 minute
test-interval.
The graph <tt class="docutils literal">vmwareO_runtime</tt> helps tracking the runtime.</li>
</ul>
</blockquote>
<ul class="simple">
<li><tt class="docutils literal">>> <span class="pre">server-script</span> statistics:</tt></li>
</ul>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal">runtime_d</tt> is the time <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt> needed to parse the last
client-message (in seconds) and will almost always show "0" as (g)awk only
has a time accuracy of one second (to my knowledge). In future versions of
<em>Vmware-Monitor for Xymon (VMX)</em> the <tt class="docutils literal">runtime_d</tt> might be calculated as an average from multiple runs
to provide something useful.</li>
</ul>
</blockquote>
</div>
</div>
<div class="section" id="manual-testing-advanced-debugging">
<h1><a class="toc-backref" href="#table-of-contents">8 Manual testing / advanced debugging</a></h1>
<p>server-side testing:</p>
<ol class="arabic simple">
<li>(optional but helpful) create a test-file w/ _one_ user-status:</li>
</ol>
<blockquote>
<ol class="loweralpha">
<li><p class="first">stop the Xymon client on the vMA</p>
</li>
<li><p class="first">on the Xymon server run (as monitoring-user of course):</p>
<pre class="literal-block">
~/server/bin/bbcmd hobbitd_channel --channel=user cat >teststatus.txt
</pre>
</li>
<li><p class="first">on (vMA-) client sent one status (as monitoring user):</p>
<pre class="literal-block">
~/client/bin/bbcmd /usr/lib/hobbit/client/ext/vmware-monitorc
</pre>
</li>
<li><p class="first">CTRL-C the hobbitd_channel from a)</p>
</li>
</ol>
<p>Now <tt class="docutils literal">teststatus.txt</tt> contains one complete user-channel datagram that can
be fed to <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt> for debugging.</p>
</blockquote>
<ol class="arabic" start="2">
<li><p class="first">on the server feed the <tt class="docutils literal">teststatus.txt</tt> through <tt class="docutils literal"><span class="pre">vmware-monitord</span></tt>:</p>
<pre class="literal-block">
cat teststatus.txt | ./vmware-monitord
</pre>
<p>The above command would not send any status to the Xymon server as the Xymon
environment is missing. To send the status messages to the Xymon-server
use:</p>
<pre class="literal-block">
cat teststatus.txt | ~/server/bin/bbcmd ./vmware-monitord
</pre>
</li>
</ol>
<p>simulating a client-message:</p>
<ul>
<li><p class="first">save the <tt class="docutils literal"><span class="pre">$BBTMP/msg.vmware-monitor.txt</span></tt> status, e.g. to
<tt class="docutils literal"><span class="pre">status-test.txt</span></tt></p>
</li>
<li><p class="first">run <tt class="docutils literal"><span class="pre">vmware-monitorc</span></tt> in manual mode, feeding that status:</p>
<pre class="literal-block">
$ ~/client/bin/bbcmd ./vmware-monitorc -d -m $PWD/status-test.txt
</pre>
<p>This would print everything to stdout, to send the recorded state of
<tt class="docutils literal"><span class="pre">status-test.txt</span></tt> to the Xymon server omit the "-d".</p>
</li>
</ul>
</div>
<div class="section" id="legal">
<h1><a class="toc-backref" href="#table-of-contents">9 Legal</a></h1>
<p>Company, product, or service names used in this document may be trademarks or
service marks of the respective owerns.</p>
<hr class="docutils" />
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[1]</td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id2">2</a>, <a class="fn-backref" href="#id4">3</a>)</em> While using a <em>vSphere CLI</em> installation on a machine of your choice is
possible it is strongly recommended to use the vSphere Management Assistant
(vMA) 4.0 provided by VMware as a pre-configured and ready-to-run virtual
appliance (see: <<a class="reference external" href="http://www.vmware.com/go/vma4">http://www.vmware.com/go/vma4</a>> and
<<a class="reference external" href="http://communities.vmware.com/community/vmtn/vsphere/automationtools/vima">http://communities.vmware.com/community/vmtn/vsphere/automationtools/vima</a>>
for details)</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id7" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[2]</td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id5">2</a>)</em> RPMs for hobbit and xymon are generously provided by Buchan Milne and
can be found here: <<a class="reference external" href="http://staff.telkomsa.net/packages/">http://staff.telkomsa.net/packages/</a>>.</td></tr>
</tbody>
</table>
</div>
</div>
<div class="footer">
<hr class="footer" />
Copyright © 2009, 2010 Thomas Eckert, <a class="reference external" href="http://www.it-eckert.de/">http://www.it-eckert.de/</a>
</div>
</body>
</html>